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Preface 


Magento 1.3: PHP Developer's Guide will guide you through development with 
Magento, an open source e-commerce platform. Exploring commonly approached 
areas of Magento development, Magento 1.3: PHP Developer's Guide provides you 
with all the information you'll need to get a very solid understanding of developing 
with Magento. 


What this book covers 


Chapter 1, Magento 3.1: PHP Developer's Guide shows you what this book will cover 
entirely in detail for you to read through. 


Chapter 2, Installing/Upgrading Magento and Preparing for Development will prepare 
you for development with Magento as well as showing you how to install and 
upgrade Magento using a variety of different methods. 


Chapter 3, Magento's Architecture introduces you to Magento's architecture, the 
Zend framework, and how the system works from a development point of view. 


Chapter 4, Shipping Modules in Magento shows you how to put together shipping 
modules in Magento to handle shipping calculation and information. 


Chapter 5, Building a Payment Module for Magento guides you in putting together 
payment methods in Magento and building connecting modules between Magento 
and the payment gateway of your choice. 


Chapter 6, Building a Basic Featured Products Module walks you through building a 
featured product module into your web site so that you can show featured products 
in your Magento categories. 
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Chapter 7, Fully-Featured Module for Magento with Admin Panel shows you how to put 
together a fully featured module in Magento as well as giving it a full backend to 
manage data with. You'll also learn how to use the module creator to quickly deploy 
module skeletons to use yourself in the future. 


Chapter 8, Integration of Third-Party CMS will show you how to integrate Wordpress 
with your Magento installation. It will also show you the other options available 
should you use any other content management systems. 


Chapter 9, Magento's Core API guides you through the Magento Core API and how 
to utilize it with scripts of your own to interface with Magento's data. 


Chapter 10, Importing and Exporting Data shows you how to work with import and 
export data profiles in Magento to work with basic order, product, and customer data. 


Appendix, Resources for Further Learning, contains additional resources for further 
learning. Its not a part of this book and it can be downloaded from Packt's website 
|| www. packtpub. com/files/7429-Appendi x-Resouces-for-Further-Learning. 
pdf. 


What you need for this book 


You will need an installation of Magento, either on your local machine or on a 
remote server, your favorite code editor, and permissions to manipulate files. 


Who this book is for 


If you are a PHP developer who wants to understand the architecture of Magento, 
learn how to extend the system with PHP code, add new features, and integrate 
Magento with a third-party CMS, this book is for you. 


You are expected to be a confident PHP 5 developer. No experience of Magento 
development is expected, although you should be familiar with the operation of 
Magento. No experience of the Zend framework is expected. 


Conventions 


In this book, you will find a number of styles of text that distinguish between 
different kinds of information. Here are some examples of these styles, and an 
explanation of their meaning. 


Code words in text are shown as follows: "We can include other contexts through 
the use of thei ncl ude directive." 
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A block of code is set as follows: 


public function _prepareLayout() 


{ 
return parent:: preparelayout(); 
} 
public function getHell oworl d() 
{ 
return ‘Hello world'; 
} 


When we wish to draw your attention to a particular part of a code block, the 
relevant lines or items are set in bold: 


public function _prepareLayout() 


{ 
return parent:: prepareLayout(); 
} 
public function getHel!l oworl d() 
{ 
return ‘Hello world'; 
} 


Any command-line input or output is written as follows: 


# cp /usr/src/asterisk-addons/configs/cdr_mysql.conf.sample 
fetc/asterisk/cdr_mysql.conf 


New terms and important words are shown in bold. Words that you see on the 
screen, in menus or dialog boxes for example, appear in the text like this: "clicking 
the Next button moves you to the next screen". 


[ VI Warnings or important notes appear in a box like this. ] 


[ Q Tips and tricks appear like this. | 
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Reader feedback 


Feedback from our readers is always welcome. Let us know what you think about 
this book— what you liked or may have disliked. Reader feedback is important for us 
to develop titles that you really get the most out of. 


To send us general feedback, simply send an email tof eedback@packt pub. com, and 
mention the book title via the subject of your message. 


If there is a book that you need and would like to see us publish, please send 
us a note in the SUGGEST A TITLE form on www. packt pub. com or email 
Suggest @packt pub. com. 


_ If there is a topic that you have expertise in and you are interested in 
Na either writing or contributing to a book on, see our author guide on 
www. packt pub. com/ authors. 
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Customer support 


Now that you are the proud owner of a Packt book, we have a number of things to 
help you to get the most from your purchase. 


Al Downloading the example code for the book 
Q Visitht tp: // www. packtpub. com/files/code/7249 Code. zip 
to directly download the example code. 
The downloadable files contain instructions on how to use them. 


Errata 


Although we have taken every care to ensure the accuracy of our content, 
mistakes do happen. If you find a mistake in one of our books— maybe a mistake 
in the text or the code— we would be grateful if you would report this to us. 

By doing so, you can save other readers from frustration, and help us to 

improve subsequent versions of this book. If you find any errata, please report 
them by visiting http://www. packt pub. com/ support, selecting your book, 
clicking on the let us know link, and entering the details of your errata. 

Once your errata are verified, your submission will be accepted and the errata 
added to any list of existing errata. Any existing errata can be viewed by selecting 
your title from http://www. packtpub. com support. 
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Piracy 

Piracy of copyright material on the Internet is an ongoing problem across all media. 
At Packt, we take the protection of our copyright and licenses very seriously. If you 
come across any illegal copies of our works, in any form, on the Internet, please 
provide us with the location address or web site name immediately so that we can 
pursue a remedy. 


Please contact us at copyright @packt pub. com with a link to the suspected 
pirated material. 


We appreciate your help in protecting our authors, and our ability to bring you 
valuable content. 


Questions 


You can contact us at questi ons@packt pub. comif you are having a problem with 
any aspect of the book, and we will do our best to address it. 
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Magento 1.3: PHP 
Developer's Guide 


After developing a site or two in Magento, we would want to take our development 
a step ahead. Magento 1.3: PHP Developer's Guide is a book for those developers 
who want to work with the Magento e-commerce platform. In this book, we will be 
guided through the fundamentals of development with Magento. 


If we're either frustrated with the "give you all the code" tutorials and articles online 
or actually really prefer them then, we'll find comfort in the code examples given 

in this book. Each code block in the book is followed by a detailed piece-by-piece 
explanation of what each part of the code does. This way, we can get information 
about not just the functionality, but also learn about the inner workings of the code 
being implemented. 


Practical knowledge focused on common requirements of any Magento 

development is gained in this book, in both the day-to-day environment, as well as 
casual pick-it-up-when-you-need-it situations. This book will add to our development 
knowledge, once we go through it thoroughly. We will learn the following: 


e Bettering our standards - We'll begin to understand the standards of 
Magento development and learn the outline of Magento itself, following 
through to the core architecture. 


e Providing an extremely solid base for development. - The solid base, built 
by reading this book and following the practical examples in this book, will 
enable us to experiment with Magento's functionality and extend it in ways 
unheard of previously. 


e The ability to solve frequently occurring issues. - The time spent developing 
with Magento will help us in resolving frequently occurring issues. We'll 
learn to build payment and shipping modules. We'll also learn how to 
interact with the Magento Core API and importing/ exporting data for 
our websites. 
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Extending Magento 


In this book, we'll be extending Magento in four core areas throughout. These can 
be broken down into the following: 


e Extensions of existing functionality with new modules that extend the 
functionality of Magento beyond the module's capability. 


e Brand new pieces of functionality that will seamlessly integrate with 
Magento's infrastructure to introduce new features to the overall Magento 
system, beyond its core base. 


e Payment and Shipping methods which implement either special formulas 
for processing payment and shipping, or integrate with existing gateways 
of other providers. 


e Wordpress CMS integration to implement Wordpress data into a Magento 
store, both through a sidebar display block and a blog using our Magento 
theme template. 


With each of these methods for extending Magento, we'll go through how existing 
modules within Magento do it and how we can too, building real-world examples as 
we go along. 


Practical examples will be used and explained block by block as we go along. 

Every piece of code is run through to start, allowing us to skim through the chapters 
when we need the code in a hurry. It is also then backtracked over to ensure that 
proper understanding and meaningful explanation is given to every block that is 
placed into our modules or scripts. This ensures that no function is unknown, once 
the code it written. 


We'll extend Magento throughout this book, without touching any of the core 
files in the installation. This means that the methods taught in this book and those 
used throughout this book, will not affect the core installation of Magento. When 
upgrading, we won't need to worry about module malfunctioning. 


Core development functionality coverage 


In this book, we will cover several topics that we encounter when programming 
with Magento. These vary from functionality you will touch upon in every single 
site you build or maintain that is using Magento to functionality that will be touched 
upon not quite so much, but is equally as important to be aware of when developing 
with Magento. 
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Core principles of development 


We'll learn everything from building modules that are not touching upon 
Magento's core installation, to the file structure of Magento, to the core principles 
of development with Magento in this book. 


System maintenance 


Important factors such as upgrading Magento and installed modules, backing 
up internal system data, and fixing commonly occurring issues will be covered 
in this book. 


Payment and shipping module development 


We'll learn how to build both payment and shipping modules while reading this 
book. These will expand upon Magento's base and provide additional functionality. 


Module development 


We will build several modules in this book, from basic modules that bring additional 
features to Magento, to fully featured extensions that manage data in the backend 

of Magento, as well as having dynamic frontends and their own dedicated URL 
structure for display. 


Data portability and interaction 


Probably the biggest factor in choosing any content management system has to, be 
whether or not we can get the data in or out of the system. Whether or not it will 
integrate with our existing systems is also a large concern. 


In this book, we'll cover mass importing and updating of data via Excel documents 
and the built-in Core API. These will allow integration with existing backend or 
internal systems. We'll also cover how to integrate Magento with third-party content 
management systems. 


Chapter overview 


The chapters in this book vary greatly in terms of what they teach, to ensure that 
as many topics are covered as possible. This ensures that in depth knowledge of 
development is gained from them. 
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The following topics on Magento development will be covered: 


Installing, upgrading, and preparing for 
development 


We'll start by walking through the server requirements for installing Magento 

and proceed onto how to check manually and how to check automatically using a 
prepared script that Magento provides for you to check hosting environments prior 
to installing Magento on them. 


Installing Magento manually will be covered step by step, from downloading 
Magento to uploading the contents of the zip file to our server and going through the 
installation right to the end. Upgrading will then be covered to ensure that Magento 
installations are kept up to date with the latest updates released by Varien. 


We'll walk through how to perform both these actions through a Secure Shell 
connection to be able to use your root server access to speed up the upgrade and 
installation process as well as automate it. SVN (Subversion) users will be able to 
keep the installation updated using Magento's repository. Overall, this chapter will 
make sure Magneto's installation and upgrade process can fit into our workflow and 
suit our hosting environment setup. 


System architecture 


In this chapter we'll run through the architecture behind Magento's system, covering 
the core file structure and through to how the template system works. This will be 
important to understanding Magento as a whole and placing our files in the right 
place when beginning development. It will help break down the barriers between 
approaching Magento for the first time and developing your first project that plague 
most developers. 


We'll learn more about the Zend Framework and how it powers Magento's core 
architecture. This will be explained for a better understanding of Magento's structure. 


We'll also go through the best methods for backing up data within Magento, to make 
sure you're covered before doing anything drastic with your installation and that any 
data is safe from loss going forward. 
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Shipping modules 


Every Magento installation uses Shipping modules to give the user the option of 
how their items are delivered to them once they are paid for. In this chapter, we'll 
be learning how to build a basic shipping module for Magento that will form a 
module skeleton of functions which can be used in further development of shipping 
modules. We'll go through what other shipping modules have done and what's 
possible when building shipping modules for Magento. 


Proceeding from there, we'll build a basic shipping module with a few methods 
applied to it, which will put what we've learned into practice. 


Payment modules 


Payment modules are vital in Magento, and we'll walk through how to build a basic 
skeleton of a payment module, in the payment module chapter. From this, we'll 
learn how they are structured and how to build the base before advancing ahead to 
something better. 


We'll learn how to add basic events to our payment module to advance it towards a 
fuller integration than expected from a basic module. 


Basic module creation and implementation 


We'll learn the basics of module creation to build a simple featured-products module 
implementation which features products on a per category basis. This will outline 
the principles of structure and implementation of a basic module development useful 
for further development. 


In addition to this, we'll run through some quick tips that will help with 
Magento development. We'll try to resolve a few common issues that arise 
during development. 


Fully-featured module development with 


administration panels 

With this chapter, we'll be delving deeper into Magento by building a basic brand 
management module. This will manage brands and display their details, which will 
be output in a dynamic template that has its own dynamic URL. 
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This chapter will show the implementation and functioning of the administration 
section inside Magento, which allows management of our module from the backend. 
We'll then use this module and its backend for getting a dedicated URL on the 
frontend and a dynamic output for the managed data. 


We'll also go through using the Module Creator script, put together by <cr edi t > 
to speed up our module creation process in the future. This will cover the base 
installation of the Module Creator script and how to put it to use. 


Integration of third-party CMS 


In this chapter, we'll be covering third-party CMS integration, the possibilities and 
the helping aids in integrating our favourite CMS into Magento for data portability. 
We'll use Wordpress as a core example and implement Wordpress into Magento 
using a popular extension. 


We'll also walk through other options available for implementation with other CMS. 
These CMS include Drupal, Typo3, Expression Engine, and Joomla!; the overview 
and options available for each are described in the chapter. 


Magento's core API 


Every installation of Magento comes with an available data API for external scripts 
and internal scripts to interact with the Magento installation's data. We'll walk 
through how it can be used, setting up the API within an installation, and handling 
error feedback when it occurs during usage. 


We'll learn about the available methods which the API offers and see examples 

of what can be done with basic outlay of what comes with a default Magento 
installation. Along with this, there will be practical examples of how to put the 

API to use with these calls to produce something viable (such as a script) to be used 
in the future. 


Importing and exporting data 

Managing data is an import aspect of Magento, and in this chapter we'll be 
discussing the built-in methods of mass customer, order, and product data available 
within Magento. 


We'll go through how to import externally located files for retrieving and storing 
information from and to external sources, to mass update or export information with 
our Magento installation. 





[12] 





Chapter 1 





Summary 

This book aims to provide us with a solid foundation of knowledge to develop a site 
upon by using Magento. The ideas gained by reading this book will enable us to use 
Magento to build something advanced. 


The internal functioning of Magento will be explained in depth, along with 
extending the present functions. This book will help us in developing our ideas 
into and onto Magento's default installation. 
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Installing/Upgrading 
Magento and Preparing for 
Development 


In this chapter, we will get everything setup in order to begin development with 
Magento. We will go through the four methods that are available when installing 
and upgrading our Magento installation, so that we're able to pick the one that best 
suits our path in development. 


Please note: upgrading is not a requirement of installing Magento, but it will be 
covered in this chapter. This will ensure that we're able to upgrade the system, as 
necessary, when an upgrade is released for Magento. Upgrading ensures that the 
system remains bug free and secure. 


Requirements 


The following are the specifications that Magento requires in order to run at a base 
level. These are not the requirements for tens of thousands of products but will have 
Magento running a small installation. These specifics are copied directly from the 
requirements page on Magent oCommerce. com for maximum reliability: 
e Supported operating systems 
° Linux x86, x86-64 
e Supported Web Servers: 
° Apache 1.3.x 
° Apache 2.0.x 
° Apache 2.2.x 
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e Supported Browsers: 


o 


Microsoft Internet Explorer 6 and above 


fe) 


Mozilla Firefox 2.0 and above 


fe) 


Apple Safari 2.x 


[0] 


Google Chrome 


[0] 


Adobe Flash browser plug-in should be installed 


e PHP Compatibility: 
° 5.2.0 and above 


Required extensions: 
° ~=PDO_MySQL 


° simplexml 
° mcrypt 

° hash 

° GD 

° DOM 

° iconv 


° SOAP (if Webservices API is to be used) 


Safe_mode off 


fe) 


Memory_limit 32M or more 
e MySQL: 


o 


4.1.20 or newer 


o 


InnoDB storage engine 
e SSL: 


° If HTTPS is used to work in the admin, SSL certificate should 
be valid. Self-signed SSL certificates are not supported 


e Server - hosting - setup: 
° Ability to run scheduled jobs (cr ont ab) with PHP 5 


fe) 


Ability to override options in. ht access files 


= We can keep up to date with the latest system requirements for 
Ka Magento at the following URL: http://www. magentocommerce. 
com/system-requirements 
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To check that our development setup meets the system requirements (mentioned 
previously), Magento Commerce provides an automated solution that can be 
downloaded and placed on our server. The script can be downloaded from: 
http://www. magentocommerce.com/_media/magento-check. zip. After 
downloading this file, we must unzip it into a directory and upload the contents 

into our directory in which we want to install Magento. Then, we simply navigate 
our browser to the URL, appending it with / magento- check. php to run the file. 
This file starts with a <? PHP short tag, as opposed to a <? php PHP opening tag. 
We'll have to change that in the file, if our server does not have short tags enabled on 
the PHP configuration. 


m The script's URL will appear on the download script's knowledge base entry: 
Ka http://www. magentocommerce. com knowl edge- base/entry/ how- 
do-i-know-if-my-server-is-compatible-with- magento. 


When you run the PHP file to check the requirements and your server meets them, 
you'll see a screen along the lines of the following: 





Congratulations! Your server meets the requirements for Magento. 


You have PHP 5.2.0 (or greater) 
Safe Mode is off 

You have MySQL 4.1.20 (or greater) 
You have the curl extension 

You have the dom extension 

You have the gd extension 

You have the hash extension 

You have the icony extension 

You have the merypt extension 
You have the pere extension 

You have the pdo extension 

You have the pdo_mysq] extension 
You have the simplexml extension 











If the Magento check fails, the server administrator or web host is to be consulted 
for advice. 


For instructions on dealing with other operating systems, 


“ae there are plenty of Magento Commerce Wiki entries available at 
http://www. magentocommerce.com/download/noregister. 


Just click the How to Get Started tab. 
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Once a Congratulations message (similar to the one in the previous screenshot) is 
displayed, then we're ready to proceed onto the installation. 


Types of installation 


We'll go through all the methods available for the installation of Magento, to extend 
our knowledge. It's not necessary to know all of them, but it will help us discover 
our preferred methods and the one which moulds itself to our development practices 
the best. 


There are four methods of installation available for Magento: 


e Manual—manually downloading and uploading all files needed 


e Downloader—downloading a script for some of the files which when 
uploaded and run, will download the rest. 


e SSH—connecting to the server via shell and running a set number of 
commands which will download, unzip, and set all the file permissions 
correctly for us 


e Subversion (SVN) —checking out or exporting from the repository to 
our server, before committing to the local directory where we would like 
our installation 


Manual 


This method of installation is dubbed Manual, as we will have to do all the 
downloading and uploading ourselves. None of the other methods make us do this 
and will automate at least small parts of the process. Unfortunately, not everybody's 
server environment allows the use of the other methods for various reasons. So, the 
Manual method is vital for those stubborn or restricted hosting environments where 
we have no other choice. 


Installing 


We'll start by going to the Magento Commerce download page online, at 
http://www. mgentocommerce. com downl oad. 
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English $ 


M Magento' ECOMMERCE PLATFORM FOR GROWTH Login + Register Job Board `= Store (0 items) 











1008 users online 9 





Dov 





Product | Services | Support | Resources Customers | Partners | Company | Blog Community Magento Connect 


Home» Download Magento 
Download Magento 
Download Magento eA 
Download Release Archives nw lo Get Started Release Notes 
Diff Files 





Downloader - the downloader will install the latest stable Magento version 





ver 1.3.2.1 - Added June 1, 2009 |=) Select your format $ DOWNLOAD x 3 
Professional Services 
Leverage the maximum power of 
Full Release - stable version Magento to achieve your 
ver 1.3.2.4 - Added September 23, 2009 = Select your format $| DOWNLOAD 
Sample Data - must be installed prior to the basic Magento Installation 
ver 1.2.0 - Added December 29, 2008 => Select your format $| | DOWNLOAD 
Magento Job Board 
Get the job done! 


Pr 


Database Repair Tool er 7, ¥ 
` B I o Al 5 = 
ver 1.0- Added August 11, 2009 E Select your format | DOWNLOAD resem ar 


Integrating Magento with Lightspeed 





Preview Release - not recommended to be used in a production environment POS 
= - pictureline - Salt Lake City, UT 
ver 1.4.0.0-betal - Added October 6, 2009 |=) Select your format $| DOWNLOAD Posted 3 days ago 


Senior Magento Developer 
WeAreDigital - Melbourne, Australia 


Magento and Zend Server - Unified Installer Posted 4 days ago 


ver 1.0.0 - Added November 9, 2009 |=) Select your format DOWNLOAD 


Pr 


Senior PHP Entwickler (m/w) fuer 
anspruchsvolle Software-Projekte 
Zalando GmbH - Berlin 

Posted 6 days ago 

















From here, we choose Full Release and download in the appropriate format. There 
isn't any difference in the formats apart from the size. If we're unsure about the 
format which our computer can unzip, then its better to simply choose the most 
universally compatible format, the . zi p format. 
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Once we've downloaded our archive of the Magento files, we expand the archive and 
get our full listing of files, as shown in the following screenshot: 





Dua 404 à ` as 
isang install.php php.ini.sample 
E app a js ~™) pkginfo 
Ee = items Eee 11 items i, 4 items 
7 p lib report 
cron.php Eee SS items S > items 
© downloader > Se skin 
Siem’ E LICENSE_AFL.txt T 
mM favicon.ico LICENSE.txt STATUS.txt 
index.php itabi A peen a) tems 
index.php.sample —_ pear 











One thing to note about the directory structure is that it contains the downloader 
and the pear file for two of the other methods for installing/ upgrading. So we're 
free to switch to other methods for upgrading, after an initial Manual install. 


Once we've expanded the archive of files that we have downloaded, we connect to 
our FTP server, navigate to the folder where we want our Magento installation to 
reside in, and upload everything. 


When the upload process finishes, we must ensure that the folders and contents of 
the folders (mentioned below) are set to 0755 in CHMOD permissions: 


e /app/etc/ 
e = /var/ 
e / medi a/ 


We proceed by navigating to the URL of our chosen install location. There are two 
ways to progress from here: 


e By following the graphical interface and the instructions on-screen to 
complete the installation of Magento. 


e By navigating to/ app/etc/ and finding the! ocal.xml.template file. We 
duplicate this file and save it as | ocal. xml . Then we fill in all the details 
between the tags. This is best done after the first install of Magento, so 
that we can see how the data is formatted after the template is used by the 
graphical interface for populating data. 
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Those who choose the graphical interface option should see the following when 
navigating to the URL of our chosen Magento installation location: 


M Magento 


Demo Store 





Installation Welcome to Magento's Installation Wizard! 

Download 

License Agreement Open Software License ("OSL") v. 3.0 

Localization This Open Software License (the "License”) applies to any original work of authorship (the "Original Work") whose owner 
Configuration (the "Licensor’) has placed the following licensing notice adjacent to the copyright notice for the Original Work: 

Create Admin Account 


You're All Set! Licensed under the Open Software License version 3.0 


Grant of Copyright License. Licensor grants You a worldwide, royalty-free, non-exclusive, sublicensable license, for the 
duration of the copyright, to do the following: 
Having trouble installing Magento? 


Cheek out our installation Guidë è to reproduce the Original Work in copies, either alone or as part ofa collective work 


æ to translate, adapt, alter, transform, modify, or arrange the Original Work, thereby creating derivative works ("Derivative 
Works”) based upon the Original Work 

æ to distribute or communicate copies of the Original Work and Derivative Works to the public, with the proviso that 
copies of Original Work or Derivative Works that You distribute or communicate shall be licensed under this Open 
Software License 


[E lagree to the above terms and conditions, 








Help Us to Keep Magento Meallhy - Report All Bugs (ver. | 3.2.4) 


Magento is a trademark of Irubin Consulting Inc. DBA Varlen. Copyright © 2009 irudin Consulting Inc 





The license agreement for Magento covers what we can and cannot do with the 
software. It's important to read it throughly (if we have the time) as it gives us a 
fantastic insight into the inner workings of the Open Source movement and how the 
licensing process works. 
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Presuming that we agree to abide by the terms, we then tick the box and click 
Continue to proceed to the next stage of the installation. 


M Magento 


Demo Store 





Installation Localization 

Download -| Locale settings |— 

License Agreement 

Localization Locale * | 
Configuration English (United Kingdom} / English (Unite $ 

Create Admin Account 

You're All Set! Time Zone * Default Currency * 


o 


GMT Standard Time (Europe/London) 4 British Pound Sterling 


Having trouble installing Magento? 
Check out our Installation Guide 


* Required Fields 








Help Us to Keep Magento Healthy - Report All Bugs (ver. 1.3.2.4) 
Magento is a trademark of Irubin Consulting Inc. DBA Varien. Copyright © 2009 Irubin Consulting Inc 





This screen allows us to set the default locale, the time zone, and the initial 

currency for our Magento installation. These can all be changed, once we go into the 
administration after installation finishes. However, it's best to set them right away so 
that we don't have to change them later. Clicking Continue after configuring these 
variables takes us onto the Configuration screen of the installation. 
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M Magento 


Demo Store 








Installation Configuration 

License Agreement 

Localization Host* Database Name * 
Configuration localhost magento 

Create Admin Account 


You can specify server port, ex.: locathost:3307 
If you are not using default UNIX socket, you can 
specify it here instead of host, ex. 
(var/run/mysqid/mysqid.sock 


You're All Set! 


Having trouble installing Magento? 
Check out our installation Guide User Name * User Password 


root 


Tables Prefix 


(Optional, Leave blank for no prefix) 


Base URL* 
http:/www.example.com/ 


Admin Path * 
admin 


Additional path added after Base URL to access your Administrative Panel (e.g. admin, backend, control etc.) 


O Skip Base URL validation before next step 


Check this box only if it is not possible to automatically validate Base URL 


O Use Web Server (Apache) Rewrites 


You could enable this option to use web server rewrites functionality for improved search engines optimization. 
Please make sure that mod_rewrite is enabled in Apache configuration. 


O Use Secure URLs (SSL) 


Enable this option only if you have SSL available 





options |- 


Save session data In 
File system 


* Required Fields 


ntinue 








Help Us to Keep Magento Healthy - Report All Bugs (ver. 1.3.2.4) 


gento is a trademark of Irubin Consulting | DBA Varien. Copyright © 2009 Irubin Consulting Inc 
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We'll break this screen down by section, as it is much longer than the previous screens. 


Database Connection 


Host, Database Name, User Name, and User Password are all the details 
Magento needs to connect to the database we created to install Magento into. 


Tables prefix will set up a prefix for all table names in the database if we 
wish to keep our Magento tables separate from anything else, in case we 
have placed something inside the database. 


Web access options 


Base URL, the installation URL on which the Magento installation will reside. 


Admin Path, which will be appended onto the end of the Base URL to gain 
access to the administration of our Magento installation. 


Skip Base URL validation allows us to skip validation of the URL at which 
the installation resides. Base URL validation typically causes issues if setting 
a system up for a URL other than the one where we uploaded our files. 


Web Server Rewrites will enable search engine friendly URLs for our system. 
(mod_rewrite must be installed and activated, as it is required on our 
Apache web server for Web Server Rewrites to work) 


Secure URLs will enable the installation's SSL, if we already have one set up 
for the URL on which we'll be setting up our installation. 


Session storage options 


This provides us a choice between storing sessions in the file system or the database. 
The difference is: 


Storing sessions in a file system enables quicker access if we're only going to 
have just Magento running on one server 


Storing sessions inside a database allows easier clustering when deploying a 
Magento installation across multiple servers for load balancing 


The next screen is the final one and will finish the process of installation through the 
graphical interface. It is the screen for creating an Admin account. 
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M Magento 
Demo Store 
Installation Create Admin Account 
Download Personal Information 
License Agreement 
Localization First Name * Last Name * 
Configuration 
Create Admin Account 
You're All Set! Email” 
Having trouble installing Magento? 
Check out our Installation Guide 
Username * 
admin 
Password * Confirm Password * 
[Encryption Key | 


Magento uses this key to encrypt passwords, credit cards and more. If this field is left empty the system will create an 
encryption key for you and will display it on the next page 


* Required Fields 








Help Us to Keep Magento Healthy - Report All Bugs (ver. 1.3.2.4) 
Magento is a trademark of Irubin Consulting Inc. DBA Varien. Copyright < 9 Irubin Consulting Inc 








The previous screen is straightforward; all the information in it is about the Admin 
account, which we'll use to access our system. The only part to take particular notice 
of is the Encryption Key field at the bottom. It is advisable to leave it blank in the 
case of a standard installation. However, if we install a setup that corresponds with 
another on our server (for example, a development or a testing version of a site), then 
we will need to copy the previous key into the Encryption Key field. 
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Once we've finished this section, we'll see the standard Magento installation success 
screen that tells us our Encryption Key. It gives us links to both the backend and the 
frontend of our installation, in case we want to progress onto either. 


M Magento 


Demo Store 





Installation You're All Set! 

Conie Get ready to experience Open-Source eCommerce Evolved. 

License Agreement 

Localization Before you continue to your store, please make a note of your encryption key (Magento uses it to encrypt passwords, credit 
Configuration cards and more}. 

Create Admin Account 

You're All Set! 05353c4975d764cb1d580a52fc172c2b 


(Make sure you keep it in a safe place.) 


Having trouble installing Magento? 
Check out our Installation Guide 


Go to Frontend Go to Backend 








Help Us to Keep Magento Healthy - Report All Bugs (ver. 1.3.2.4) 


Magento is a trademark of Irubin Consulting Inc. DBA Varien: Copyright © 2009 Irubin Consuiting Inc 





Upgrading 
When an upgrade is required for our site, we can manually update Magento using 
the following routine. An upgrade is not required directly after an initial install. 


To upgrade the installation — using the Manual method with a full package 
download — we have to: 
e Back up our core files (for "just incase it goes wrong" purposes only) 
° Back up the database 


° Back up all code that we have modified ourselves (modules, 
themes, skins, and so on) 


° Back up our media directory, which contains all uploaded 
images for categories or products 


° Back up our/app/etc/local.xml file, which contains our 
database configuration and encryption key 


e Upload all files from our downloaded full release file. We can either: 


° Skip overwriting the backed up files and upload everything 
else or 
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° Overwrite all backed up files and then re-upload them to 
their appropriate directories 
e Clear our/var/ cache and/var/sessi on directories to ensure no data from 
the previous install version lies around unwanted 


e Point the browser to any page in the Magento installation to run the upgrade 
script from the previous version to the current version and we're done! 


Downloader 


The advantage of the downloader is that we have a much smaller initial download. 
Later the script can download the bigger files, saving the extra time taken to set up 
Magento. This reduces the initial download from between 40-50 MB to 1 MB and 
is especially useful for slower connections. It also means we can stay away from 
FTP when it comes to upgrading in the future, as the downloader also allows us to 
upgrade existing installations that have been installed using other methods. 


Installing 


To download from http://www. magentocommerce. com/ downl oad, we select 
the Downl oader package. Expanding that displays a directory that looks similar 
to next screenshot: 





aesenen LICENSE.txt vap 
Gee = tems rer Gee o items 
favicon.ico i media 
U 16 x 16 2 items 


teess 
index.php ka pear 
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Next, we upload everything to the chosen Magento installation directory and 
load / downl oader/ URL in our browser. A screen welcoming us to the downloader 
is displayed: 





M Magento 
Demo Store 
Installation Welcome to Magento's Installation Wizard! 
Download s z s 
You are now ready to continue the installation process by downloading the most up-to-date copy of the Magento software. 
License Agreement 
Localization 


Configuration 
Create Admin Account 
You're All Set! 


Having trouble installing Magento? 
Check out our Installation Guide 








Help Us to Keep Magento Healthy - Report All Bugs (Do 
Magento is a trademark of Irubin Consulting Inc. DBA Varien, Copyrig 08 onsulting Inc 





Once we click on Start the download process, we'll be presented with a screen that 
shows us the download progress. We must be patient, as it could take a long time 
before anything comes up. We should keep our browser window open and ensure 
that it isn't disrupted in any way. When it's done, the page will look similar to the 
next screenshot: 
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M Magento 


Demo Store 





Installation Welcome to Magento's Installation Wizard! 


Download 

License Agreement 
Configuration 

Create Admin Account 
You're All Set! 


You are now ready to continue the installation process by downloading the most up-to-date copy of the Magento software 


M Auto-scroll console contents 





Having trouble installing Magento? 
Check out our Installation Guide 





© Download completed. You can proceed with installation 











Continue Magento installation 








Help Us to Keep Magento Healthy - Report All Bugs (Downloader ver. 1.3.2.1} 
Magento is a trademark of Irubin Consulting Inc. DBA Varien. Copyright © 2008 Irubin Consulting Inc. 





After clicking on Continue Magento Installation at the bottom of the page, we 
progress onto the standard GUI in order to complete the installation. We can refer 
to the previous section (Manual installation) to learn about installation using the 
standard GUI. 
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Upgrading 
Once an update is available for Magento, we can load the/ downl oader/ directory 
onto our chosen Magento installation URL. We are prompted with a login screen. 


Magento MANAGER 


Log In 





Please re-enter your Magento Adminstration Credentials. 


Only administrators with full permissions will be able to log in 





Username: magento 





Password:  sssssesessssssss 








Magento is a trademark of Irubin Consulting Inc. DBA Varien. Copyright © 2008 trubin Consulting Inc- 





We type in our administration Username and Password for the chosen 


Magento installation into the boxes, after which, we're be allowed into the 
downloader interface. 
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Magento MANAGER 


Extensions | Settings | Return to Admin Log Out 


EJ Search for modules via Magento Connect. 
EJ Paste extension key to install: 





Manage Existing Extensions Check for Upgrades 


Clear all sessions after successfull install or upgrade: C} 


Channel: connect.magentocommerce.com/core 


Package Name Installed Actions 
Interface_Adminhtmi_Default 1.2.1.2 (stable) i 


Summary 
TĘ) Default interface for Adminhtmi 


Interface_Frontend_Default 1.2.1 (stable) { 


TA) Default interface for Frontend 


Interface_Install_Defauit 4.2.4 (stable) I) Default interface for Install 

Lib_Google_Checkout 1.2.0 (stable) { TA) Google Checkout Library 

Lib_Js_Calendar 4.2.0 (stable) í JẸ) Javascript Calendar for Magento 

Lib_Js_Ext 1.0.18800 (stable) TE) Extjs Javascript Libraries for Magento 

Lib_Js_Mage 4.2.1 (stable) n TA) Javascript Libraries for Magento 

Lib_Js Prototype 1.2.0 (stable) ( iE) Prototype and Scriptaculous Javascript Libraries for Magento 


Lib_LinLibertineFont 1.1.4 (stable) C TA) Libertine Open Fonts Project fonts for PDF print-outs 





Lib_Varien 4.2.4 (Stable) i W Varien Library 

Lib_ZF 1.7.2.1 (stable) H Zend Framework 

Lib_ZF_Locale 1.7.24 (stable) ( TA) Zend Framework Locale 

Mage_All_Latest 1.2.1.2 (stable)  [ 78) Metapackage for latest Magento 1.2 release 
Mage_Core_Adminhtm! 1.2.1.1 (stable) i c=] Magento Administration Panel 
Mage_Core_Modules 1.2.1.2 (stable) C - E] Collection of Magento Core Modules 
Mage_Downloader 1.2.1 (stable) ( E] Magento Downloader 


Magento is a trademark of Irubin Consulting Inc. DBA Varien. Copyright © 2008 Irubin Consulting Inc. 








Here we can install new extensions (should we want to), at the top of the page. 


Below, we find a Check for Upgrades button and a list of the extensions currently 
installed. We can select re-install or un-install actions from the drop-downs for 
each extension as we wish, and commit all the changes at once using the button at 


the bottom. 
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As we're upgrading, we would want to click on the Check for Upgrades button at 
the top. Once the page has refreshed from checking for upgrades, we'll see all the 
extensions that have available upgrades highlighted in the table. 





(stable) = 
i 1.7.2.1 — 
Lib_ZF Locale H Zend Framework Locale 
(stable) = 
12.4.1 1.2.1.2 (stable tay Metapackage for latest Magento 1.2 
Mage_All_ Latest ( ) Upgrade to 1.2 H$] p 9 g 
(stable) (1.0kB) <” release 
1.2.11 _ 
Mage_Core_Adminhtm! od Magento Administration Panel 
(stable) 
Mage_Core_Modules pana Ve he ee? | Upgrade to 1.2 F$] Collection of Magento Core Modules 
u! K ui 
ere (stable) (1421kB) ace een g 
1.2.1 (stable -~ 
Mage_Downloader 1.2.0 (stable) (17 he ) | Upgrade to 1.2 H Magento Downloader 
Installed | Commit Changes | 
Upgrade Available 











Select Upgrade to... from the drop-down, in the extensions you want to upgrade, 
and click Commit Changes at the bottom of the page. After doing this, a dialog area 
appears which shows the progress, similar to how the install dialog appeared for 
showing progress during installation. 





 Auto-scroll console contents 





Procedure completed. Please check the output frame for useful information and refresh the page to see changes. 











We can access any URL in our Magento installation and all mySQL upgrades will 
take place to complete the upgrade. 
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SSH (Secure Shell) 


SSH is the fastest of the four installations and upgrade options for Magento and 

a preferred choice of the four. It is command line only and enables us to do the 
entire process without the use of any GUI, besides the client that we use to run the 
commands. It is typically available only on dedicated hosting environments and 

will be available to those who have root access to the contents of their hosting server 
environment. The majority of shared hosting or reseller hosting will not provide SSH 
access or root access. VPS usually provide root access similar to dedicated hosting 
environments, but it's not standard everywhere. 


For each of these stages, we must ensure that we're connected via SSH to our server, 
using the following command: 


ssh username@server address 


Note that the server address can be a direct URL or the IP address of the server 
that we are connecting to. Afterwards, we will be prompted for our username's 
password. Once we have done that, we'll be logged in and can get to the planned 
installation's directory. The command to get there is: 


cd /full/path/to/installation/directory/ 


We're ready to install/ upgrade, once we're inside the directory of the chosen 
installation address. 


Installing 


Like the downloader, we will still need to run through the GUI after installation. 
However, this will be much quicker and we will get real time feedback on what is 
happening, once we start executing the commands. 


The first line is spread over two lines due to the length of the URL from where the 
download is fetched. We have to insert that as a single command. We'll be installing 
version 1.3.2.4. We need to switch all occurrences of this version number with the 
most current version so that it installs the most recent version of Magento. 


wget http://www. magentocommerce.com/downloads/assets/1,.3.2.4/ magento- 
1,3.2,.4,.tar.gz 

tar -zxvf magento-1,.3.2.4.tar.gz 

mv magento/* magento/.htaccess . 

chmod o+w var var/. htaccess app/etc 

chmod -R o+w media 

./pear mage-setup . 
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./pear install magento-core/Mage All _Latest-stable 
rm -rf downloader/pearlib/cache/* downl oader/ pearli b/ downl oad/* 
rm-rf magento/ magento-1.3.2.4.tar.gz 


Mac users should replace the line beginning with wget with the 
following: 


curl http://www. magentocommerce.com/downl oads/ assets/1.3.2.3/ magento- 
1.3.2.3.tar.gz > magento-1.3.2.3. tar.gz 


From here, we can access our chosen Magento installation location via HTTP and 
follow the graphical user interface to complete the installation. 


_ There is a way to bypass the installation wizard, but it requires the reader 
e to know all the correct variables to proceed into the required areas. 
GA Information on it can be found at: htt p:// www. magentocommerce. 
com wiki/groups/227/ command line installation wizard. 


Upgrading 

Upgrading is just as simple as installation. Go to the directory of the Magento 
installation you wish to upgrade and run the following: 

./ pear mage-setup . 

./pear install magento-core/Mage All Latest 

rm -rf downloader/pearlib/cache/* downl oader/ pearli b/ downl oad/ * 


After we've executed the previous command, the Magento installation will be 
upgraded. We'll just need to access it at its appropriate URL, as with the other 
methods, and all MySQL related updates will take place. 


If we need to clear our cache and sessions, we can use the following command: 


rm -rf var/cache/* var/session/ * 


SVN (Subversion Network) 


For those unfamiliar with Subversion, there are numerous links in the Appendix 
where we can learn about what it is, what it does, and how it can be used on our 
platform of choice. 
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For those familiar with SVN already, there is an available SVN repository setup, 
if we want to use it. Those already trained in working with SVN will only need to 
know the following command to keep the installation up-to-date or to install it at 
another location: 


svn export http://svn. magentocommerce.com/source/branches/ 1.3 


There is also atr unk setup for versions in progress and in alpha testing, though it is 
advisable to not use it in any production environments. In case we want to test it, we 
can do so with the following command: 


svn export http://svn. magentocommerce.com/source/ branches/ 1, 3- trunk 


These commands relate to the 1.3 string of Magento, so for future versions you will 
need to replace the version number in the commands. 


Summary 


In this chapter, we've learned how to install and upgrade Magento in all four 
methods available to us. We can now do the following: 


e =Install/ upgrade manually, by downloading/ uploading all files and backing 
up the appropriate files we need to 

e Install/ upgrade via the downloader 

e = Install/ upgrade via SSH 

e =Install/ upgrade via SVN 
In the next chapter, we will learn about the structure of Magento and the inner 
architecture that makes Magento work. This is key to understanding how to develop 
with it. Whether it is themes, skins, modules, or moving it from server to server, 


the next chapter will teach us how to handle Magento and where to find what we 
looking for when we need to. 
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Magento's Architecture 


Magento has a wonderful architecture behind its system. It's a very strict architecture 
that relies on us knowing where the files should be placed and how to structure our 
templates and modules. But this is part of what makes Magento a great system, in 
that it enforces these standards. 


Here in this chapter, we will learn about this architecture and how it applies to 
development with Magento. We will learn: 


Where everything is within Magento 

What all the base directory files and folders do 
The basics of how the template system works 
How modules work within the system 

How the Zend Framework fits into the equation 


The best methods for backing up Magento 


Magento's base structure 


The fundamental knowledge of Magento's architecture begins with its file structure. 
It's important to know what goes where by default, so that we may position our 
new files accordingly, especially in terms of ensuring that our development doesn't 
overwrite core files. 
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Base directory 


The default installation contains the following files and directories in the 
base directory: 


Each of these files and directories has a different purpose. We'll go through them 
to ensure that we understand the function of each. This will help us later, if ever 
we need to find something specific, or when developing. It will also be helpful 
when we'll be looking to place the files coming out of our new module into the 


„htaccess 

. htaccess. sample 
404 (directory) 

app (directory) 
cron. php 

downl oader (directory) 
favicon.ico 
index. php 

index. php.sample 
js (directory) 

lib (directory) 
LICENSE AFL. txt 
LICENSE.txt 

media (directory) 
pear 

pkginfo (directory) 
report (directory) 
skin (directory) 
var (directory) 


appropriate directory. 
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The function of each of the files in the base 
directory 


The following is a run through of all the files in the base directory, to show us what 
they do: 


e „htaccess — This file controls mod_rewrite for fancy URLs and sets 
configuration server variables (such as memory limit) and PHP maximum 
execution time, so that Magento can run better. 


e .htaccess.sampl e — Works as a backup for. ht access,so that we know 
the default. htaccess file (if ever we edit it and need to backtrack). 


e cron. php —The file that should be executed as a cr on job every few 
minutes to ensure that Magento's wide caching doesn't affect our 
server's performance. 


e favicon.ico —Magento's default f avi con; it's the small icon that appears 
in the toolbar of our browser. 


e index. php —The main loader file for Magento and the file that 
initializes everything. 

e index.php.sampl e —The base template for new i ndex. php files, useful 
when we have edited the i ndex. php file and need to backtrack. 


e LICENSE AFL. txt —It contains the Academic Free License that Magento 
is distributed under. 


e LICENSE.txt —It contains the Open Software License that Magento is 
distributed under. 


e pear —This controls all automatic updating via the downloader and SSH. 
This file is initialized and handles the updating of each individual module 
that makes up Magento. 


e php.ini —A sample php.ini file for raw PHP server variables 
recommended when setting up Magento on our server. This should not be 
used as a complete replacement, but only as a guide to replace certain lines 
of the php. i ni server file. It is useful when overriding these variables when 
htaccess isn't enabled on our server. 








[39] 


Magento's Architecture 





The function of each of the folders in the base 
directory 


The following is a run through of all the folders in the base directory to show us 
their contents: 


404 — The default 404 template and skin storage folder for Magento. 


app — All code (modules), design (themes), configuration, and translation 
files are stored in this directory. This is the folder that we'll be working 

in extensively, when developing a Magento powered website. Also 
contained in this folder are the template files for the default administration 
theme and installation. 


downl oader — The web downloader for upgrading and installing Magento 
without the use of SSH (covered in Chapter 2). 


j s — The core folder where all JavaScript code included with the installation 
of Magento is kept. We will find all pre-compiled libraries of JavaScript here. 


| i b — All PHP libraries used to put together Magento. This is the core code 
of Magento that ties everything together. The Zend Framework is also stored 
within this directory. 


medi a —All media is stored here. Primarily for images out of the box, this 
is where all generated thumbnails and uploaded product images will be 
stored. It is also the container for importing images, when using the mass 
import/export tools (that we'll go through in Chapter 10). 


pkgi nf o — Short form of package information, this directory contains text 
files that largely operate as debug files to inform us about changes when 
modules are upgraded in any way. 


report —The skin folder for the reports that Magento outputs when any 
error occurs. 


skin — All assets for themes are stored within this directory. We typically 
find images, JavaScript files, CSS files, and Flash files relating to themes, 
in this directory. However, it can be used to store any assets associated 
with a theme. It also contains the skin files for the installation of skins and 
administration templates. 


var — Typically where we will find all cache and generated files for Magento. 
We can find the cache, sessions (if storing as files), data exports, database 
backups, and cached error reports in this folder. 
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The template system architecture 


The template architecture is broken into three areas — two for development of the 
theme and one for the containment of the assets: 


/app/design/frontend/default/<templ ate name>/ 


° | ayout/ —For all the XML files declaring which module tied 
functions should be called to which template files 


° temp! ate/ —For all the templates processing the output that 
is passed from functions called from | ayout/ and structured 
into the final output to the user. 


/skin/frontend/default/<templ ate_name>/ —For the containment 


of all assets relating to our template, images, CSS, Flash, and JavaScript. 


Structural blocks and content blocks 


Each theme contains structural and content blocks. Structural blocks are the ones 
that lay out the theme into sections. Let's take a look at a three-column layout. 
The following are the structural blocks in a three-column layout: 


header 
left 
content 
right 


footer 
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Here's a visual representation of those structural blocks laid over the Magento 
demo store: 











In each of the structural blocks, we then have content blocks that give each structural 
block its content for output to the browser. Let's take the right column; our content 
blocks set for this column on a standard theme could be: 

e mini cart 

e recently viewed products 

e newsletter subscription block 


e poll 
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Here we have a visual representation of these content blocks on top of the Magento 
demo store: 





Magento search 
Demo Store 


store links _ 

















mini cart 
callout | ‘compare | 
product - products 
listing | 
| | callout 
callout = 
poll 
popular 
tags 











footer links 


hein Us to Keep Magento Heatly Report An Byer (ver TAZA 
2 200H Magento Demo Lora Ail Raits Roservad 





On receiving a request from a user connecting to our site to view the page: 


1. Magento will load the structural areas 
Each structural area will be processed through 
Magento will gather the content blocks assigned to each structural area 


PON 


It will then progress through the content block template for each structural 
area, to process the output 


5. It sends all of this back as final output to the user, who then views the 
Magento page that was requested 
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XML layout files 


To assign blocks to each of these structural blocks, Magento loads an XML layout file 
for each request. This XML layout file is called by the URL that the user is accessing 
on the site. It declares all modules that are to be loaded in each structural area of the 
site. On top of this, we have apage. xml file, which is the default loader for all pages 
on the site. 


A layout XML file is typically structures as follows: 


<default> 
<reference name="header'> 
<block type="page/html header" name="header" as="header"> 
<block type="page/template links" name="top.links" 
as="topLlinks"/> 
<block type="page/switch" name="store language" 
as="store_language" 
template="page/switch/| anguages. phtml "/ > 
<block type="core/text_list" name="top.menu" as="topMenu"/ > 
</block> 
</reference> 
</ default > 


In the above code, we have: 


e <def aul t >—The handler for the URL, in this case default will load no matter 
what other handler is being initialized 


e <reference>—The reference structure which calls the blocks in our theme 


e =<block>—A content block which defines the type of block and the template 
which will process the block's outgoing data in the system 


In addition to this, Magento uses actions within blocks for functions which need to 
process the data that is input to them, for example adding CSS stylesheets: 


<block type="page/html_head" name="head" as="head"> 
<action method="addCss"> 
<stylesheet> css/menu.css </stylesheet > 
</action> 
<action method="addCss"> 
<stylesheet> css/clears.css </stylesheet > 
</action> 
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<action method="addltem'> 
<type>js</type> 
<name>varien/iehover-fix.js</name> 
<params/ > 
<if>lt IE 7</if> 
</action> 
<action method="addCss"> 
<stylesheet >css/print.css</stylesheet > 
<params >media="print"</ params > 
</action> 
<action method="addCss"> 
<stylesheet> css/print.css </stylesheet > 
<params> media="print" </params> 
</action> 
</ block> 





We'll notice that there are several tags within the action method tag. These are 
processed into an array and then passed through the action met hod="" parameter, 
in this case addCss. This function then places the input into an output, ready for its 
appropriate template. 


= Layouts are fully explained online in Magento's designer guide: 
Ka http://www. magentocommerce.com/ design gui de/ 
articles/intro-to-layouts. 


Hierarchical file processing 


When creating new themes, we do not have to worry about copying all the theme 
and skin files from the default theme over to our new one. Let's presume that we 
have an additional theme called new_t heme, alongside our def aul t theme. Our 
theme calls files called | ogo. gi f andi mage. gi f on one of its pages. 
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The themes that we have contain the following files in their skin's images directory: 








default new_theme 
logo.gif logo.gif 
image. gif 

test. gif 





Magento would process this main requesting | ogo. gif andi mage. gi f . As 
new_theme is our current active theme, it will pull | ogo. gif from there., However, 
asi mage. gif does not exist innew_t heme, Magento would grab that from def aul t. 
So now, it works like this: 








Requested file Theme it will come from 
logo.gif new theme 
image. gif default 





Similarly, ift est. gi f were called in our template then it would come from the 
default theme. If we upload an image called t est. gi f to the image directory of 
new_t heme, then it would immediately come from there instead. 


This applies to all files for themes in Magento, which include the following: 


e Templates 
e Layout XML files 
e Anything in the theme skin folders 


z Magento's template architecture and hierarchy is also explained online 
GA in the designer's guide to Magento: http://www. magentocommerce. 
com design guide 


Modules and how they work within the 
system 


Magento primarily works on a base of modules. All functionality is divided up 
into modules that make up the system overall. It's important to understand what 
each module does and how to go about adding modules to the system, in order to 
understand the architecture of modules themselves. 
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Distribution of the modules between 
directories 


All modules are located within the / app/ code/ directory. Directories are commonly 
referred to ascodePools. There are three possible locations for all modules that 
relate to the system. They are all split by type to prevent any confusion: 


communi t y — For community-distributed extensions, usually those that we 
have installed through Magento Connect or have downloaded from a source, 
other than our own. Anything installed through Magento Connect will be 
installed here automatically. 


core —Reserved for core Magento modules, so that we cannot directly 
overwrite or interfere with them. We keep our modules out of core to avoid 
any conflict with the core modules or any future updates. Anything from a 
Magento upgrade or any new Magento modules will go into this directory. 


Local —This is where we should be placing our modules when they are 
either under local development or are not distributed among the community. 
It's best to keep anything that we develop in this directory, so as to not 
interfere with the core or community modules. Nothing will be automatically 
installed here, unless we have physically uploaded it. 


Modules included with Magento 


Included modules in the core folder of default Magento installation are as follows: 


Mage_Admin 

Mage AdminNotification 
Mage Api 

Mage Backup 

Mage Bundle 

Mage Catalog 

Mage Catalogl ndex 
Mage Cataloglnventory 
Mage CatalogRule 

Mage CatalogSearch 
Mage Checkout 
Mage_Cms 

Mage Contacts 

Mage Core 
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e Mage Cron 

e Mage Customer 

e Mage Dataflow 

e Mage Directory 

e Mage Downloadable 
e Mage Eav 

e Mage GiftMessage 
e Mage GoogleAnalytics 
e Mage GoogleBase 

e Mage GoogleCheckout 
e Mage GoogleOpti mizer 
e Mage_ Install 

e Mage_Log 

e Mage Media 

e Mage Newsletter 

e Mage Page 

e Mage Paygate 

e Mage Payment 

e Mage Paypal 

e Mage Paypal Uk 

e Mage Poll 

e Mage _ProductAlert 
e Mage Rating 

e Mage Reports 

e Mage Review 

e Mage Rss 

e Mage Rule 

e Mage Sales 

e Mage SalesRule 

e Mage _Sendfriend 

e Mage Shipping 

e Mage Sitemap 

e Mage Tag 

e Mage Tax 
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e Mage Usa 
e Mage Weee 
e Mage Wishlist 


Setting up the folder structure of a module 
Let's presume that we want to set up a module's folder structure, ready 

for development. Our module's core folders will be placed in/ app/code/| ocal / 
Book/Example/. 


These folders will primarily be used for storing our code that makes the module 
work. The folder structure breaks down as follows: 


e Block/ 
e controllers/ 
e etc/ 
e Model / 
° Mysql 4/ 
. Book/ 
e sql/ 


° book_setup/ 


Typically, developers will pick or choose each folder, depending on whether or 
not they're going to use it within their module. 


Note that Model / Mysql 4/Book/ has its first letter in uppercase, whereas 
sql/book_setup/ does not. We must be sure to keep this the same way throughout 
our development. 


Template files for the frontend of our module will be stored as follows: 
e XML files will be stored in/app/design/frontend/ <i nterface>/ <theme>/ 
layout/exampl e/ 
e Output files will be stored in/ app/ desi gn/ 
frontend/ <interface>/<theme>/templ ate/ exampl e/ 
Any admin template files for the frontend of our module will be stored as follows: 
e XML files will be stored in/ app/ desi gn/ 
admi nht ml / <interface>/<theme>/| ayout/exampl e/ 


e Output files will be stored in/ app/ desi gn/ 
admi nhtml / <interface>/ <theme>/templ ate/exampl e/ 
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Here's a breakdown of what each folder is for: 


e 8lock/ —For processing of all display blocks called by the system for the 
module. These are controllers that will be called in the XML layout files 
within a theme, in order to display something. 

e controllers/ —Our controllers that support the application and structurally 
keep things together. 


e etc/ —Configuration files for the module, for declaring things such as the 
default options when installed and declaring all blocks, models, and install/ 
upgrade actions. 

e Model / —For placement of all models to support controllers in the module. 


e sql / —SQL actions when the module is installed/ upgraded/ uninstalled. 


Zend Framework and its role within 
Magento 


Magento (at its raw PHP base) is built on the Zend Framework. From the database 
class to the handling of URLs, Magento is in its raw form, with Zend Framework 
doing all the work. Alongside this, Varien has built several core modules on top of 
the Zend Framework, in order to tie it altogether into the system as we know it. 


What is Zend Framework 


Zend Framework's official site best describes the framework as follows: 


Zend Framework (ZF) is an open source framework for developing web applications 
and services with PHP 5. ZF is implemented using 100% object-oriented code. The 
component structure of ZF is somewhat unique; each component is designed with 
few dependencies on other components. This loosely coupled architecture allows 
developers to use components individually. We often call this a "use-at-will" design. 
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While they can be used separately, Zend Framework components in the standard 
library form a powerful and extensible web application framework when combined. 
ZF offers a robust, high performance MVC implementation, a database abstraction 
that is simple to use, and a forms component that implements HTML form rendering, 
validation, and filtering so that developers can consolidate all of these operations 
using one easy-to-use, object-oriented interface. Other components, such as 
Zend_Auth and Zend_Acl, provide user authentication and authorization against all 
common credential stores. Still others implement client libraries to simply access to 
the most popular web services available. Whatever your application needs are, you're 
likely to find a Zend Framework component that can be used to dramatically reduce 
development time with a thoroughly tested foundation. 


How Zend Framework works 


The Zend Framework (at its core) is designed to be used as a package or separate 
modules. This (among other features) makes it unique, as most other frameworks 
are designed to be used plainly as frameworks or not at all. 


However, the Zend Framework comes with classes that allow us to use it as a 
standalone framework and develop with it as one. Instead of being delivered with a 
preset amount of directories and layout for developers, it only suggests a layout for 
our files. This means that we can adapt the framework to meet our current workflow 
and choose how much we adapt the workflow to fit the framework. 


It's role and effect in Magento 


The Zend Framework allows Magento to focus on the core issues at hand. It removes 
a lot of the work on the database and core structural classes and puts the work 
towards fixing and adding to core modules of Magento. 


Most importantly it gives developers a standard approach to development that they 
can move across and apply to Magento. The standard development practices help 
greatly in adopting Magento as a platform and make it easier for developers having 
experience with Zend Framework to adapt to Magento. 


= More information on learning the Zend Framework and resources can be 
V found at the back of this book in the Appendix attached. Its official site is 
located at:http://framework.zend.com/. 
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Backing up Magento's data 
It's important to know how to back up our site, to ensure that our installation's data 
is not lost (if ever things go bad). 
It is recommended to back up our Magento installation: 

e Regularly as a base to ensure that there are incremental backups 

of our system 
e Before installing new modules or themes from Magento Connect 
e When developing modules 


e Before upgrading our system 


Backing up the files 


We will need to back up all the files relating to the Magento installation, when 
backing up our system. Two of the ways in which this can be done are given below. 


Manually 


Manually, we are able to download all the files of the installation to our hard 
drive. This is the longest method of backing up the files and is the most foolproof 
method available. 


Using SSH 
Using SSH, we're able to vastly speed up the duration of backing up the servers. 
We can do this in two ways: 


e Zipping up all files, if the server has it enabled 
e Copying all files to another directory 


Both of these depend on whether or not our server has SSH. So if this isn't available 
to us, then we cannot use these methods. 
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= Both of these methods require us to connect to our server via SSH first 
GA and then use the c d command to get to the directory (which Magento is 
installed in), before running the commands. 


Zipping up all files 
This will create a zi p file of our entire Magento installation's files and folders called 
magento archive. zip. 


tar cf magento_archive.tar * 

Tountar this archive, extract the files afterwards: 

tar -xvf yourfilename.tar 

We can then move this to another directory of our choice using the mv command: 


mv magento archive.zip /path/to/new/destination/ 


Copying all files to another directory 


We run the following command to copy all files (as they are) into another directory 
on our server. We'll replace the full path with the path to the desired directory, into 
which we want to copy all the files. 


cp -R * /path/to/ new/ desti nation/ 


Backing up the database 


We'll need to back up the database as part of our Magento backup. Let's go 
through how. 
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Using the system itself 


Magento comes with a built-in method for backing up our installation and keeping 
several backups logged, in case we want to download older backups at any time. It 
can be found in the System menu under Tools: 


My Account 
Notifications = 


Manage Currency Rates | 
Transactional Emails 
Permissions 


Manage Stores 


Configuration 











The initial screen will be similar to the next screenshot: 


aiiai Logged in as admin | Sunday, 29 March 2000 | Lon Out 


Dashboard Sales Catalog | Customers Promotions Newsletter CMS Reports System ® Get help for this page 














Page f1 of 1 pages | View [2 per page | Total 0 records found | Reset Filter | Search | 
| Time + Size, byte Type Download Action 
From: iz] [ All types E] 

To: =] 


No records found. 
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To create a backup via the System panel, all we need to do is click on Create Backup 
in the upper-right of the screen and wait for it to finish: 





~ z Global Record Search Logged in as admin | Sunday, 29 March 2009 | Log Out 
Magento” Admin Panel [Global Record Search i og Ou 
Dashboard = Sales | Catalog | Customers Promotions Newsletter CMS Reports | System ® Get help for this page 
© Backup successfully created 
Ñ Backups =o 
Page 1 of 1 pages | View EZ] per page | Total 1 records found [Raset Fitter | |" Search | 
Time + Size, byte Type Download Action 
From: E] | All types | 
To: =| 
29 Mar 2009 10:04:57 45517 DB Gz (The archive can be uncompressed with 7-Zip on Windows systems) Delete 











The process of creating a backup can take quite a while (especially for bigger 
databases), so we will need to keep an eye on our server's memory limits and PHP 
execution limits. These are set in our. ht access file on runtime, but some servers 
will only run the defaults and not allow them to be overridden. If we encounter a 
white screen instead of the success message (shown in the previous screen), then 
the problem is either memory limit or execution time limit. We will need to increase 
them ourselves or contact our web host. 


Once the backup is completed, however, we'll be able to find it in our/ var / 
backups/ folder. They will be named by timestamp and the highest numbered 
filename will be the last to be backed up. 


Using phpMyAdmin 
The most common back up solution is phpMyAdmin, and some people prefer it over 
any built-in method. To export via phpMyAdmin, we: 
1. Navigate to the database 
Switch to the export tab 
Select all tables and SQL as the export type 
Under options on the right-hand side select Disable foreign key checks 


Select save as file at the very bottom of the page 


ano Fe YN 


If we want to match the compression type of Magento's output, select 
gzipped as our compression method 


7. Click the Go button to export 
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This will give us an SQL file, which we can then import at a later date back into an 
empty database and restore our data. 


Summary 


In this chapter, we've learned the following: 


How Magento's folder structure and files are laid out 

What each of the base directory's folders and files do 

How the template system works 

How modules work within Magento 

About the Zend Framework and how it benefits Magento 

How best to go about backing up Magento and when to go about it 


Further to this chapter, I want you to read the Magento designer's guide and the 
Zend Framework documentation and examples. There are also a very good group 
of links for you to read through in the Appendix at the back of this book. These will 
increase your knowledge of the Magento architecture and benefit you throughout 
this book. 
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Shipping Modules in Magento 


In this chapter, we will apply our newfound knowledge of Magento's core 
architecture (that we learned in the previous chapter) and apply it to one of 
the fundamental building blocks of Magento, its shipping module. 


Here, we will learn how to create a shipping module, so that we can develop 
our own when the need arises. By the end of this chapter we will: 


e Know where to find shipping modules that others have produced 


e Know how to put together a basic shipping module and know what 
values pertain to what information 


e Be able to create our own methods for calculation or handling shipping 
with Magento 


What shipping modules do 


Shipping modules are used to define the handling of the order, before it goes 
through the payment method section of the order process. They take the order itself 
and decide how to go about charging and delivering it to the customer. Magento 
takes the order through each shipping module that is installed and active in the 
system. Each shipping module is then able to process the order currently in the cart 
and present any available options to the user, from what it sees in the order. 


For example: we have a shipping module in our system that provides free 

delivery to people located within the UK and ordering over £40. Let's presume 

that we are ordering £50 worth of goods and are located within the UK. When 

the order is sent through this module, it checks whether or not the user is in the UK 
and the order total is over £40. If these conditions are met, (which our order does), 
then we are presented with a free delivery option, among others, to choose during 
our order process. 


Shipping Modules in Magento 





This is a very simple version of what a shipping module can do. The full range of 
what can be done using shipping modules can be grasped by looking at Shipping 
Modules on Magento Connect and finding what it has on offer. Here's a small range 
of what has been made public: 


Royal Mail UK, EU, and Worldwide Shipping module — For calculation and 
handling of all of Royal Mail's shipping methods using weight and distance. 
This module sends key product information to Royal Mail via their API, 
authenticating with information that the Magento store administrator has 
input, and outputs pricing for various shipping options on the current order. 


Regional Free Shipping module — Gives the Magento administrator 

the option to allow free shipping by region, instead of by country. This 
provides a choice to the store administrator of breaking down free shipping 
further than country. For example, this would be good for someone who 
runs a store based in Nottingham that wants to reward local customers in 
the East Midlands, as opposed to simply giving free shipping to the entire 
United Kingdom. 


Basic Store Pickup Shipping module — Enables customers to choose 
between picking up the item themselves and having it delivered to them. 
This is advantageous for companies which use Magento and have a physical 
store presence with stock held. 


Magento Connect can be accessed at the following URL: 
http://www. magentocommerce.com/magento-connect. 


Aa 
G 


The three core types of shipping module can be summarized in the following: 


Third-party API and/or web service integration. For integration with 
existing couriers that have web-based APIs or web services that offer the 
same for organization of your shipping. Many existing services make an 
API available to us for integrating into Magento. We should check Magento 
Connect for any existing modules that others have created. 


Using customer data to provide unique calculations and opportunities to 
certain users. Anything that the customer puts in it while checking out can 
be used for this type of module. 
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e Shipping methods that involve a physical store or location for additional 
options that compliment others. We could theoretically build up a set of 
stores under the Magento store company's business. We could then link 
them up with local computers at the locations and use the shipping module 
to check for stocks at each location. We should do that before suggesting the 
store as a location for the user to be able to pick up the item. 


How to begin with a shipping module 


Here we'll be learning about how to begin with a shipping module. This is the 
skeletal structure of a shipping module that we can use as a template for any 
shipping module which we create. We will also be using it to create a very basic 
shipping module at the end of this chapter. 


For the purpose of following this tutorial, we will be creating all files in/ app/ code/ 
local /MagentoBook/ Shi ppi ngModul e/ , which will be the base directory for all 
files created (from this point onwards). We must make sure that this directory 

and sub-directory are set up before continuing onwards. This means that if the 

file is declared to be/ hel | 0/ wor Id. php, we place this on the end of our initial base 
address and it becomes / app/code/local/Magent oBook/ Shippi ngModul e/ hel | o/ 
world. php 


Please start by creating the directory MagentoBook in /app/code/local/ anda 
sub-directory within that called Shi ppi ngModul e, creating the directory structure 
/MagentoBook/ Shi ppingModule/. 


The configuration files 


We create / app/code/local/MagentoBook/ShippingModule/etc/config. xm in 
our module's folder. Here, we'll place the following code which will declare our new 
module for use, make it depend on Mage_Shi ppi ng being enabled, set it at version 
0.1.0 and allow it to use the existing global database connection which is set up for 
our store. 


<?xml version="1.0"?> 
<config> 


<modul es > 
<MagentoBook_ Shi ppi ngModul e> 
<version>0.1.0</version> 
<depends> 
<Mage_Shipping /> 
</ depends > 
</MagentoBook_ Shi ppingModul e> 
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</ modul es > 


<gl obal > 
<model s> 
<shi ppingmodul e> 
<class>MagentoBook ShippingModule Model </class> 
</shi ppingmodul e> 
</ model s> 


<resources> 
<shippingmodule setup> 
<setup> 
<modul e>MagentoBook_ Shi ppingModul e</ modul e> 
</setup> 
<connection> 
<use>core setup</use> 
</connection> 
</shippingmodule setup> 
</resources> 
</ global > 
<default> 
<carriers> 
<shippingmodul e> 
<model >MagentoBook/carrier_ Shi ppingModul e</ model > 
</ shi ppingmodul e> 
</carriers> 
</ default > 
</ confi g> 


Let's walk back through this code and go over what each individual section does. 


We start by defining our XML header tag for the file, to ensure that it is accepted 
as an XML file when read by the XML parsing class in the system. 


<?xml version="1.0"?> 


We define the <conf i g> tag, to ensure that everything within it is read as 
configuration variables to be loaded into Magento's configuration for whatever 
we define internally within this tag. 


<config> 


We define the <mo dul es > tag, so that we're setting configuration variables for 
modules defined within this tag. 


<modul es> 
<MagentoBook_ Shi ppi ngModul e> 
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We set the module's version number to 0. 1. 0, to supply Magento with versioning 
for the module in the future, if we update and need to perform statements within 
the update portion of the module, so as to execute above a certain version number. 


<version>0.1.0</version> 


We have to make sure that our module cannot be activated, or possibly run, 
without the Mage_Shi pping core shipping handler and module activated. This is 
vital because the module being a shipping module is simply going to cause fatal 
errors without the parent Mage_ Shipping module providing the helper functions 
needed internally. 


<depends> 
<Mage_ Shipping /> 
</ depends > 


Next, we close off our module declaration tag and modules tag. 


</MagentoBook_ Shi ppingModul e> 
</ modul es > 


We set up our <gl obal > tag to define global assets to Magento. 


<gl obal > 


Next, we define the <model s > tag to define global models to the system and for 
setting up our module's default model to be one of those global models which is 
automatically loaded. 


<model s> 
<shi ppingmodul e> 
<class>MagentoBook ShippingModule Model </class> 
</ shi ppingmodul e> 
</ model s> 


We define the <r es our ces > tag, so that we can configure the database resources 
available to the module within the system. 


<resources> 
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Defining the <r es our ces > tag allows us to include a setup file with our module that 
accesses the database. This helps if we need to load in any variables (such as default 
table rate rules) for our module, or for loading additional data required locally by the 
module, when calculating the shipping rates. 


<shippingmodule setup> 
<setup> 
<modul e>MagentoBook Shi ppingModul e</ module> 
</setup> 


Here, we'll use the core database connection (the default one), and ensure that we do 
not overwrite the database connection set up for this particular module. 


<connecti on> 
<use>core setup</use> 
</connection> 


We close off all tag pairs, besides <conf i g>, that have been opened at this point. 


</shippingmodule setup> 
</resources> 
</ global > 


Finally, we end the configuration file with a declaration that our module is a 
shipping module and should be processed as one, within the system. This will 
register the module to the system, so that it can actually display shipping methods 
to the user on checkout. Without this, nothing will be returned to the user from 
this module. 


<default> 
<carriers> 
<shi ppingmodul e> 
<model >MagentoBook/carrier Shi ppingModul e</ model > 
</ shi ppingmodul e> 
</carriers> 
</default> 


We close the <conf i g> tag to end the XML configuration file. 
</ confi g> 


After we've done this, we need to declare our module to Magento by creating a 
configuration file in/ app/etc/modules/MagentoBook_ShippingModule. xml. 


Next, we place the following code in our new configuration file, to allow this 
module to interact with Magento and be turned on/off under the System 
Configuration menu: 
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<?xml version="1.0"?> 
<config> 
<modul es> 
<MagentoBook_ Shi ppingModul e> 
<active>true</active> 
<codePool >l ocal </codePool > 
</MagentoBook Shi ppingModul e> 
</ modul es > 
</ confi g> 


We break this file down into the individual lines: 
<?xml version="1.0"?> 


The <conf i g> wrapper tag defines the XML to be read, as a configuration of 
something inside Magento. 


<config> 
The <modul es > wrapping tag defines this as a module to Magento. 


<modul es> 


The next tag is used for defining that this is the configuration of a module entitled 
<MagentoBook_ Shi ppingModul e> and for applying the settings inside the tag to 
the module: 


<MagentoBook_ Shi ppi ngModul e> 


We make sure that it's active by default (this will be overwritten when activated/ 
deactivated in the Magento administrative back-end). 


<active>true</active> 
The <code pool > tag is used for keeping this module in our local module's directory. 
<codePool >l ocal </codePool > 
Closing tags are for closing the XML tags that we started the <conf i g> tag with. 


</MagentoBook Shi ppingModul e> 


</ modul es > 
</ confi g> 
<r codePools are explained in full detail in Chapter 3, Magento's 
o , ee ; " 
Architecture earlier in this book starting on page 47. 
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Now that we have the configuration set up, to allow the module to be managed within 
Magento and versioning control to allow for upgrades in the future, we can progress 
onto the module itself. It also means that we can now turn our module on/ off within 
the administration. To do this, we go to System | Configuration, then to Advanced 
under the Advanced heading on the left-hand side. Once here, we will be presented 
with Enable/Disable dropdowns for each module installed in the system. 





Mage_Tax Enable x| 
Mage_Usa Enable 7| 
Mage_Weee Enable | 
Mage_Wishlist Enable bd 
MagentoBook_ShippingModule Enable v| 











We'll set the dropdown for our module to Disable until we have completed the 
adaptor model and administration setup. This will prevent the module from crashing 
the system, while it is incomplete. We will re-activate the module once we're ready to 
see the output. 


The adaptor model 


The adaptor model handles the core functionality behind our shipping module. From 
its name, we can guess that it adapts what we have into a real module that works 
and functions. This is something that both shipping and payment modules have. 


This is where all the calculations happen and where everything will be coded. 
The coding is done behind the scenes to handle the shipping methods and the 
rates returned to the user to choose from in their checkout process. 


Here we apply the name of our shipping method within our bare-bones template. 
For the sake of demonstration, we'll call ours Bar eBones Met hod in the code to follow. 


Our adaptor in this case will be placed in:/ app/code/!ocal/Magent oBook/ 
Shi ppingModule/Model/Carrier/ BareBones Met hod. php 


<?php 

class MagentoBook ShippingModule Model Carrier BareBonesMethod extends 
Mage Shipping Model Carrier Abstract 

{ 


protected $ code = 'shippingmodule'; 
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public function collectRates( Mage Shipping Model Rate Request 


grequest) 
{ 
if (!$this->getConfigData('active')) { 
Mage::log('The '.$this->_code.' shipping method is not 
active.'); 
return false; 
} 


ghandling = $this->getConfigData('handling'); 
$result = Mage::getModel('shipping/rate result’); 


foreach ($response as $method) { 
$rMethod = Mage::getModel('shipping/rate_result_method'); 


gmethod->setCarrier($this->_code); 
$method->setCarrierTitle($this->getConfigData('title)); 





$method->set Met hod($method['code']); 
$method->setMethodTitle($method['title']); 


$method->setCost($method[{'amount']); 
$method->setPrice($method[' amount']+$handling); 


$result->append($method); 
} 


return $result; 
} 
} 


In this example, $r es ponse is the parsed array of an API call response to a 
third-party service and code,title,andamount are all values of the array resulting 
from the request. We'll go through this block by block, so that we're aware of the 
happenings at each stage: 
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We start by declaring our module and ensuring that it extends the shipping class of 
Magento. This tells Magento that the module is a shipping module. 


<?php 


class MagentoBook ShippingModule Model Carrier BareBonesMethod extends 
Mage Shipping Model Carrier Abstract 


{ 


protected $ code = 'shippingmodule'; 


We need to declare the standard co! | ect Rates function for Magento to call, when 
our shipping method is called. 


public function collectRates( Mage Shipping Model Rate Request 
$request ) 


{ 


We'll skip the rest if our module isn't enabled and log it to the Magento logs, so that 
we know it is being skipped. 


if (!$this->getConfigData('active')) { 
Mage::log('The '.$this->_code.' shipping method is not 
active.'); 
return false; 


} 


We want to retrieve our configured handling fee to be added later to the total fee for 
this shipping method. 


ghandling = $this->getConfigData('handling'); 


We grab our overall result that is being returned to Magento, with all available 
shipping modules and rates. We do that in case we need to add to it with any 
methods available with our module. 


$result = Mage::getModel('shipping/rate_result'); 


$response in the code below is a theoretical example that we have returning from a 
third-party API, likely via SOAP or another method. This is not a set array here, but 
used as an example for adding multiple rates based on an array. 


foreach ($response as $method) { 
We prepare the new method that will be added. 


$method = Mage::getModel('shipping/rate_result_method'); 
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Next, we record our important internal system variables that Magento will use to 
store and refer to this shipping method. 


$method->setCarrier($this-> code); 
$method->setCarrierTitle($this->getConfigData('title)); 


Moving on, we add the method's code and title returned in our array to the new 
shipping method which will be returned to the user. 


$method->set Met hod($method['code']); 
$method->setMethodTitle($method['title']); 


We set the cost, again from the returned array we have. This is not returned to the 
user, but is used internally by the system to calculate profit (price - cost = profit). 


$method->setCost($method['amount']); 


We set the price for the shipping method and add our handling fee that we gathered 
earlier from the configured administration value. 


$method->setPrice($method['amount']+$handling); 


Next, we add the rate to the result which will be returned to the system. 


$result->append($method); 
} 


The result is returned to Magento for continuing processing onto the next shipping 
module installed in the system. 


return $result; 
} 
} 


The administration setup 
Now that we have an adaptor, we need to make it configurable within the 
system. We must do so for the Magento administrator to be able to do something 
constructive with what we've built. The administrator must be able to: 

e Enter personal details 

e Set up the handling rate 

e Set the cost of the shipping method that we put into the store 
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Our administration configuration file defines how our shipping module appears 
within the system configuration; which fields appear and what they relate to are 
defined here. Once defined, the Magento administrator is able to configure the 
module using these fields to get the desired result from the shipping module. 


The file / app/ code/|ocal/Magent oBook/ Shi ppingModul e/etc/system. xml file 
contains all the administration fields for the shipping method, and will be formatted 
along the lines of the following code: 


<?xml version="1.0"?> 
<config> 
<sections> 
<carriers> 
<groups> 
<shippingmodule translate="l abel" module="shipping"> 
<label >Bare Bones Shipping inc. </label > 
<frontend type>text</frontend type> 
<sort_order>13</sort_order> 
<show_in_default>1l</show_in_default> 
<show_in_website>l</show_in_website> 
<show_in_store>l</show in sto <fields> 
<active translate="label"> 
<label >Enabl ed</| abel > 
<frontend type>select</frontend type> 
<source model >adminhtml/system config source _yesno</source model > 
<sort_order>l</sort_order> 
<show_in_default>1l</show_in_default> 
<show_in_website>1l</show_in_website> 
<show_in_store>l</show_in_store> 
</active> 
<contentdesc translate="label"> 
<label >Package Description</|!abel > 
<frontend type>text</frontend type> 
<sort_order>12</sort_order> 
<show_in_default>1l</show_in_default> 
<show_in_website>1l</show_in_website> 
<show_in_store>l</show_in_store> 
</contentdesc> 
{specific configurable fields listed here} 
</fields> 
</ shi ppingmodul e> 
</groups> 
</carriers> 
</sections> 
</ confi g> 
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In this configuration file, we've simply set the options for whether or not the 
shipping method is enabled and for a field to describe the contents of our shipping 
method to the user checking out through the Magento checkout process. We will 
learn how these fields are formatted, so that we can add our own as we want. We 
will go through this in the next section. 


Declaring further fields and learning how 
they're structured 


A large number of fields are not included ins ys tem. xml , as they can be 
overwhelming without a thorough explanation. We'll pick and choose our fields 
from the below code and insert them between the <f i el ds> </fields> tag as we 
go through the popular types of fields which can be used for the configuration of our 
module. Our fields are all built up in the same format, with the required options for 
each field being set out in the format below: 


<account transl ate="label"> 

<label >Account number </|abel > 
<frontend type>text</frontend type> 
<sort_order>7</sort_order> 
<show_in_default>1l</show_in_default> 
<show_in_website>l</show_in_website> 
<show_in_store>l</show in _store> 

</ account > 


Breaking it down, we start with the surrounding tags of <account 
translate="|abel"> </ account >, which defines the configurable variable 
account and contains its configuration. Thetrans| ate="| abel" isareference 
to the <t rans| ate> tag that we defined earlier for translation of our module (for 
multi-language stores). The value inside the tag will act as a key in the language 
file when translating. 


The <I abel > </| abel > tag pair contains the name of this configurable variable to 
be displayed within the administration. We try to make this short in most cases, with 
additional notes added where they are needed. 


The <frontend_ type> </frontend_type> tag pair defines the type of field that will 
be shown on the frontend for the administrator configuring this shipping method. 
This should be set to one of the following: 


e text—For a text-input-based form element 

e select—For a select-dropdown form element 

e multiselect —For allowing the user to select multiple options from a list 
e textarea—For a textarea-input-based form element 
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<sort_order> </sort_order > defines the order of the fields when they are output 
within the administration for the shipping method. 


The final three variables for each field (that need to be defined) decide when the 
configurable variable should appear within the administration. Their values are 
always 1 or 0 to define yes or no. Here is a breakdown of the individual tags that 
explains to us what they do: 


Tag pair What they do 

<show in_default> </show in_default> Default Magento-wide configuration 
<show_ in_website> </show_in_website>  Website-wide configuration 
<show_in_store> </show_in_store> Store-specific configuration 








There is one additional option tag that is not required, but is important for certain 
types of fields. The <source_model > </source_model > tag pair defines a source 
model which will populate options for a field. We consider the following as an 
example of this: 


<active translate="label"> 
<label >Enabl ed</| abel > 
<frontend type>select</frontend type> 
<source model >adminhtml/systemconfig source yesno</source model > 
<sort_order>l</sort_order> 
<show_in_default>1l</show_in_default> 
<show_in_website>l</show_in_website> 
<show_in_store>l</show in_store> 
</active> 


This particular source model admi nht ml/system_config_source_yesno populates 
the select field with yes and no options for selection. The raw models for exploration of 
all the available included functions for the value of this option within your field can be 
found in:/ app/code/core/Mage/Adminhtml/Model/System/Config/Source/. 


For ouradminht ml /system_config_source_yesno value, the file in question is 
Yesno. php within the same directory. 


Here are a few more source models and what they produce in our module's 
administration for the user: 


e shipping/source_handlingType —Lists Magento handling types for 
shipping modules 


e shipping/source_handlingActi on — Lists Magento handling actions for 
shipping modules 
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e adminhtml/system config source shipping allspecificcountries — 
Prints out a list containing the two core options All allowed countries and 
Specific countries 


e adminhtml/system config source country — Lists all countries in the 


system. It is usually used by means of multi-select lists for shipping modules 
and payment gateways to select the country that they should be applicable to 


Appearing in the administration 


Once this has been done, the shipping method should appear in Shipping Methods 
under System->Configuration: 


Shipping Methods 


Table rates 
Flat Rate 


Free Shipping 
UPS 





USPS 
FedEx 
Bare Bones Shipping inc. 





Enabled No z] 


Package Description 





DHL o 





Now, we will look at the most useful shipping module fields that are used when 
putting the shipping module together. These are fields with predefined names and 
types that have automatically processed the results that they output. Therefore, they 
require no additional coding in the adaptor module to take them on board; Magento 
performs these methods straight out of the box. 


Free shipping 


If we want to enable an automatic price-based amount for free shipping with our 
method, we can add in a field calledfree_shipping_enabl e and combine this with 
another field by the name offree_shipping subtotal .Whenfree_shi pping_ 
enable is set to Enabled by the Magento administrator, then Magento will 
automatically takefree_shipping_subtotal into account and offer free shipping if 
the total amount is above the value off ree_ shipping subtotal. 


If this field is disabled, Magento will simply process using the default shipping 
calculation behavior of the module. 
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The fields are set up as follows, withsort_order andshow_in_ values varying: 


<free shipping enable translate="label"> 
<label >Free shipping with mini mum order amount </!abel > 
<frontend type>select</frontend type> 
<source model >adminht ml /system_config_ source _enabl edisable</ 

Source model > 
<sort_order>21</sort_order> 
<show_in_default>1l</show_in_default> 
<show_in_website>l</show_in_website> 
<show_in_store>l</show in_store> 

</free shipping enabl e> 

<free shipping subtotal translate="label"> 
<label >Mi ni mum order amount for free shipping</label > 
<frontend type>text</frontend type> 
<sort_order>22</sort_order> 
<show_in_default>1l</show_in_default> 
<show_in_website>l</show_in_website> 
<show_in_store>l</show in_store> 

</free shipping subtotal > 


Handling 


Handling charges sometimes come into the equation and need to be added onto the 
overall transaction. Magento enables us to do this using the following source models 
to present what we want to achieve: 


<handling_ type transl ate="label"> 
<label >Calcul ate Handling Fee</|abel > 
<frontend type>select</frontend type> 
<source model >shipping/source_handlingType</source model > 
<sort_order>l0</sort_order> 
<show_in_default>1l</show_in_default> 
<show_in_website>l</show_in_website> 
<show_in_store>0</show in _store> 

</handling_type> 

<handling_action transl ate="label"> 
<label >Handling Applied</!abel > 
<frontend type>select</frontend type> 
<source_ model >shipping/source_handlingActi on</source_model > 
<sort_order>ll</sort_order> 
<show_in_default>1l</show_in_default> 
<show_in_website>l</show_in_website> 
<show_in_store>0</show in_store> 

</handling_action> 
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<handling_fee translate="label "> 
<label >Handling fee</label> 
<frontend type>text</frontend type> 
<sort order>12</sort_order> 
<show_in_default>1l</show in default > 
<show_in_website>l</show_in_website> 
<show_in_store>l</show in _store> 

</handling_fee> 


Restricting a shipping method to certain countries 


This will allow us to present the option to the administrator for filtering the shipping 
method to be only accessible to certain countries. In practice, this means that if we 
wanted to offer only one type of delivery to the United Kingdom, then we could do 
so simply by selecting United Kingdom from the multi-select field created by the 
following declaration. 


The Magento administrator can choose the specific countries from the multiple select 
list. Only orders from those countries that we have created shipping methods for will 
be processed in the shipping module. This enables them to choose any number of 
countries for restricting this shipping method to. 


<sallowspecific translate="label"> 
<label >Ship to applicable countries</|abel > 
<frontend type>select</frontend type> 
<sort_order>90</sort_order> 
<frontend class>shipping-applicable-country</frontend class> 

<source model >adminht ml /system config source shipping_ 

allspecificcountries</source_ model > 
<show_in_default>1l</show_in_default> 
<show_in_website>l</show_in_website> 
<show_in_store>l</show in_store> 

</sallowspecific> 

<specificcountry transl ate="Iabel"> 
<label >Ship to Specific countries</label > 
<frontend type>multiselect</frontend type> 
<sort_order>9l</sort_order> 

<source model >adminhtml/system config source country</source model > 
<show_in_default>1l</show_in_default> 
<show_in_website>l</show_in_website> 
<show_in_store>l</show in_store> 

</specificcountry> 

<showmethod translate="label"> 
<label>Show method if not applicable</|label > 
<frontend type>select</frontend type> 
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<sort_order>92</sort_order> 

<source model >adminhtml/system config source yesno</source_ model > 
<show_in_default>1l</show_in_default> 
<show_in_website>l</show_in_website> 
<show_in_store>l</show in_store> 

</ showmet hod> 


Using our template to create a shipping 
method 


Now that we have our bare-bones shipping module, we continue with the creation of 
something that we can see an outcome from. From this we should be able to start 
to put together our own shipping module tailor-made for future needs. 


The purpose of what we are going to build is going to be very simple: we're 
going to create a shipping module that meets the following parameters: 


e Ithas a handling fee, either per product or for the entire order 
e Itcan be limited to specific countries 


e Itcan set a simple flat-rate shipping cost, if 10 products or more are 
being ordered 


e Itcan set another simple flat-rate shipping cost, if 10 products or less 
are being ordered 


e All of the above can be configured via the Magento administration 


Before progressing, we delete the previous shipping module from our installation 

to make sure that it does not interfere with what we'll be building. To do this, we go 
back to the Magento Downloader (which we've learned about in Chapter 2) and select 
Uninstall from the module's supporting dropdown before committing the changes. 


The configuration files 


This time, we'll go with the directory Magent 0Book and the name 

Full ShippingModul e. For this, our/ app/code/!ocal/Magent oBook/ 
Shi ppingModul e/ Magent oBook/ Full Shi ppi ngModule/etc/config. xml 
file will look like: 


<?xml version="1.0"?> 
<config> 
<modul es > 
<MagentoBook_Full Shi ppingModul e> 
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<version>0.1.0</versi on> 
<depends> 
<Mage Shipping /> 
</ depends > 
</MagentoBook_FullShi ppingModul e> 
</ modul es > 


<gl obal > 
<models> 
<Full Shi ppi ngModule> 
<class>MagentoBook Full ShippingModule Model </class> 
</ Full Shi ppingModul e> 
</ model s> 


<resources> 
<full shippingmodule setup> 
<setup> 
<modul e>MagentoBook_ Full Shi ppingModul e</ modul e> 
</setup> 
<connection> 
<use>core setup</use> 
</connection> 
</fullshippingmodule setup> 
</resources> 
</ global > 
</ confi g> 








We turn on Ful | Shi ppi ngModul e, and allow it to be turned off/on from 
within the administration. Then, we create /app/etc/modules/Magent oBook_ 
Full Shi ppingModule. xml and place the following in it: 


<?xml version="1,0"?> 
<config> 
<modul es> 
<MagentoBook_Full ShippingModul e> 
<active>true</active> 
<codePool >l ocal </ codePool > 
</MagentoBook_ Full Shi ppingModule> 
</ modul es > 
</ confi g> 
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Our adaptor 


For those interested in cutting down on code, unnecessary comments have been 
removed (which were included in the previous adaptor in this chapter). 


We place the following code in: / app/code/|ocal/ Magent oBook/ 
Full Shi ppingModul e/ Model /Carrier/ Full BoneMet hod. php 


<?php 


class MagentoBook Full Shi ppingModule Model Carrier Full BoneMet hod 
extends Mage Shipping Model Carrier_Abstract 


{ 


protected $ code = 'fullshippingmodule' 


public function collectRates( Mage Shipping Model Rate Request 


$request) 
{ 
if (!$this->getConfigData('active')) { 
Mage::log('The '.$this->_code.' shipping method is not 
active.'); 
return false; 
} 
ghandling = $this->getConfigData('handling') 
$result = Mage::getModel('shipping/rate result') 





$method = Mage::getModel('shipping/rate_result_method'); 
$items = Mage::getModel ('checkout/session')->get Quot e( )- 
>getAl ll tems(); 


if (count($items) >= $this->getConfigData('minimumitemlimit')) { 
$code = $this->getConfigData('over_minimum_code'); 
$title = $this->getConfigData('over_minimumtitle'); 
$price = $this->getConfigData('over_mini mum price'); 





} 

else { 
$code = $this->getConfigData('under_mi ni mum _code') 
$title = $this->getConfigData('under_minimumtitle') 
$price = $this->getConfigData('under_minimum price') 

} 


gmethod->setCarrier($this-> code); 
$method->setCarrierTitle($this->getConfigData('title')); 
$method- >set Met hod( $code) 
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$method->setMethodTitle($title); 
$method->setPrice($price + $handling); 
gresult->append($method) ; 


return $result; 
} 
} 


In short, this will check whether there are more items in the cart than the 
pre-configured value of mi ni mum_item_!i mit and then apply a rate if it is over 
the set limit. If under the limit, it applies another rate. 


We'll go through the code in blocks, so that we can understand it better. 


First we declare our module as an extended class of Mage_Shi ppi ng, to make sure 
Magento knows it as a shipping method. 


<?php 


class MagentoBook FullShippingModule Model Carrier Full BoneMet hod 
extends Mage Shipping Model Carrier _Abstract 


{ 


protected $ code = 'fullshippingmodule'; 


We declare our col | ect Rates function, which is the standard function for Magento 
to call with the request for rates when processing through all available shipping 
methods to it when a user is at the shipping method stage of ordering. 


public function collectRates( Mage Shipping Model Rate Request 
$request) 


{ 


Here we'll use an active variable set in the backend, when the administrator wants to 
disable this shipping method. We will check if the active variable is set to true and if 
it is not, false will be returned, so that Magento does not process any further. We will 
then tell the module to write to Magento's debug log using the Mage: : | og function 
call to ensure that we're aware the module isn't being used when going through 
them at any point in our development process. 


if (!$this->getConfigData('active')) { 
Mage::log('The '.$this->_code.' shipping method is not 
active.'); 
return false; 


} 
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We get our handling fee configuration value for adding onto our shipping method 
price later on. This variable has been set in the administration of our module and 
we're getting it out of the database to be used dynamically. 


ghandling = $this->getConfigData('handling'); 


We make sure that our shipping method is declared to the system and that 
the result array is sent to the user of shipping methods, if we want to add any 
available methods. 


In practice this means that we set our method ( if available), then add this method to 
the result. The result in total (after going through all shipping modules installed in the 
system) is then returned to the user for selection of the preferred shipping method. 


We also want to get the total amount of items in the cart, as our module depends 
on it. 


$result = Mage::getModel('shipping/rate_result'); 

$method = Mage::getModel('shipping/rate_result_method'); 

$items = Mage::getModel('checkout/session')->get Quote) 
->getAllltems(); 


If the amount of items in the current order is more than or equal to the amount that 
the mi ni mum_item_li mit variable is set to, we want discounted rates. Otherwise, we 
get the standard rates, as there is no discount. 


if (count($items) >= $this->getConfigData('minimumitemlimit')) { 
$code = $this->getConfigData('over_minimum_code'); 
$title = $this->getConfigData('over_minimumtitle'); 
$price = $this->getConfigData('over_mini mum price'); 

} 
else { 
$code = $this->getConfigData('under_minimum_code'); 
$title = $this->getConfigData('under_minimumtitle'); 
gprice = $this->getConfigData('under_ minimum price'); 





} 


We now need to set the internal code Magento will refer to this shipping method as 
when setting up orders and invoices in the system. We will then set its title and price 
to also be presented in the system and to the user on the frontend who is awaiting 
presentation of available shipping methods to them. 


gmethod->setCarrier($this->_code); 
$method->setCarrierTitle($this->getConfigData('title')); 
$method- >set Met hod( $code); 
$method->setMethodTitle($title); 
$method->setPrice($price + $handling); 
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gresult->append($method) ; 


return $result; 
} 
} 


The administration configuration 


First, we'll create the / app/code/!ocal/Magent oBook/ Full Shi ppingModul e/ 
etc/system. xml file using the bare-bones template we put together earlier in this 
chapter. We start by changing our carrier label to Full Boned Shipping inc. 


<fullshippingmodule translate="l|abel" module="shipping"> 
<label >Full Boned Shipping inc. </l abel > 


Then we add our text-based fields to the system. xml configuration file, front_end_ 
type text as per the previous conventions that we used with the following labels and 
variable names: 








Variable Name Label 

mi nimum_item_li mit Minimum item quantity (if over, the over minimum 
rate is applied) 

over_minimum_code Over minimum shipping code 

over _minimumtitle Over minimum title 

over _minimum price Over minimum price 

under _mini mum code Under minimum shipping code 

under_minimumtitle Under minimum title 

under minimum price Under minimum price 





Here's a reminder of the format for the field tags and how they should be formatted: 


<active translate="label"> 
<label >Enabl ed</| abel > 
<frontend type>select</frontend type> 
<source model >adminhtml/system config source yesno</source model > 
<sort_order>l</sort_order> 
<show_in_default>1l</show_in_default> 
<show_in_website>l</show_in_website> 
<show_in_store>l</show in_store> 
</active> 


We make sure to define our sort order as we proceed. As a reminder — the 
<sort_order>1</sort_order > tag pair is how the order in which the fields appear 
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is controlled. From 1 being the field to appear first, the highest number appears last 
in sequence. 


After we have defined these fields, we add the handling fields and country 
restriction fields (outlined previously in this chapter). Once this is done, we 
have completed our configuration. 


Testing our newly built module 


We go into the administration under System->Configuration and then to 
Shipping Methods. Our new shipping method Full Boned Shipping inc. 
appears at the bottom. 





Enabled Yes zi 
Minimum item quantity (if 2 

over rate the over minimum 

rate Is applied) 


Over minimum shipping 
code 


over-two-shipping 


Over minimum titie Over Two Products special offer! 





Over minimum price 15 
Under minimum shipping standard-shipping 
code 
Under minimum title Standard Shipping 
Under minimum price 25 
Calculate Handling Fee Fixed zi 
Handling Applied Per Order xÍ 
Handling fee 5 
Ship to applicable countries | All Allowed Countries zi 
Ship to Specific countries Afghanistan oO 
Aland Islands 
Albania 
Algeria 
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We must be sure to fill out the values here in the module and save them. In the 
previous screenshot, we have a Standard Shipping method, as there are less than two 
products in the cart. It provides Over Two Products special offer! shipping option 
when the user has equal to or over that amount of products in their cart. The pricing of 
both options has been set to reflect that and a handling charge of 5 per order has been 
added, which is applied as per the base currency (Pounds in this case). 


To test the frontend, we go to the store and place x amount of products into 
the cart (either below or above the minimum item quantity set in our module) 
and progress to shipping to check if the rates are output. If we see them, then it 
works successfully! 


Code to allow our shipping module to meet 
our needs 


Here we see some small pieces of code to use within our shipping modules to 
achieve what we set out to do, when we created the module for a Magento store. 


To get all items in the cart, we use: 


$items = Mage::getModel ('checkout/session')->get Quot e()- 
>getAllltems(); 

foreach($items as $item) { 

// process each item here 

Le 


Within the items f or each loop, we get the quantity for each item that is currently in 
the cart (also a great way to advance the ful | bones modul e built above): 


$item quantity = $item->getQty(); 
We check if a product is virtual or not, so that we don't need to calculate shipping: 


if($item->get Product()->getTypelnstance()->isVirtual())f{ 
II it's a virtual product 

} else{ 
II it's not a virtual product 


} 
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Summary 


In this chapter we've learned: 


e How to set up a basic bare-bones shipping module template for use in the 
future development of shipping modules 


e How to use shipping module-specific fields to limit our shipping module 
usage to certain countries 


e How to set up a basic administration section for our shipping module to 
allow it to be configured by Magento store administrators 


e How to put together a shipping method that decides on the shipping rate by 
the amount of items in the cart 


e Some useful pieces of code to use in our own shipping modules, when 
putting them together 


Further to this chapter, we should create our own shipping modules for Magento 
stores. It is an excellent opportunity to test the knowledge gained in this chapter, 
by building modules on our own. 
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This chapter is about putting together a payment method for Magento and the 
various aspects that go together to complete the process. We'll be using our 
knowledge from Chapter 3 on Magento's architecture and grow what we've 
put into action in Chapter 4 in building our shipping module. 


In this chapter we'll go through the various parts that make up a payment 
method, including: 


e The declaration 

e The configuration 

e The functional operation 

e The administrative setup of fields 


e Tying in automatic shipping-tracking code generation and updating into 
our payment module 


How payment methods work in Magento 


When it comes to going through an order in Magento, payment methods are the 
last stage of the process. Once customer details have been filled in and the shipping 
method has been chosen, the payment method comes into play. Its role is to finalize 
the order and handle how the customer is going to pay for the item(s) that he will 
be ordering through the Magento installation. 


Magento will take all the order details, including what items are in the order, where 
it is being shipped, and all the pricing totals, after which it will proceed to the 
payment stage. Magento will load payment methods, one by one and present them 
to the customer. 


Building a Payment Module for Magento 





Once the customer has selected a payment method, then Magento will progress 
towards processing through the method's function for sending the data for 
processing. This could be anything from sending the request via an API, processing 
credit card details, or authorizing them. 


The other functions of a payment method are to handle the invoicing, capturing, 
voiding, and refunding of payment itself. These are all functions that the payment 
method will deal, which we'll go through later on in the chapter. 


Payment methods that are bundled 
with Magento 


Let's take some time here to go through the existing payment modules that are 
bundled with Magento by default, so that we may learn from them by exploring 
their inner depths. It helps a great deal when trying to underneath payment methods 
to explore the files in these bundled modules and read through the code as best we 
can, trying to understand how everything works. 


There are numerous bundled payment methods included with Magento and they 
are listed below, with their module names and the subsequent attached payment 
gateways that they integrate into Magento: 


e Amazon Payments (module folder name: AmazonPayments) 
e Authorize.Net (module folder name: PayGate) 

e Google Checkout (module folder name: GoogleCheckout) 

e Magento standard methods: (module folder name: Payment) 


[e] 


Cheque/ Money order 
° Purchase order 
° Saved CC 


° Zero Subtotal Checkout 
e PayPal (module folder names: PayPal, PayPalUk) 


Exploring through these bundled payment methods after reading through this 
chapter will hopefully give us a fuller picture of how they work. A lot can be 
learnedby jumping into the directories and files of pre-built modules that are 
out there. 
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Downloadable payment methods on 


Magento Connect 


In addition to bundled payment methods that come with Magento's default 
installation, there are well over 100 downloadable extensions on Magento Connect 
available for download. These vastly cover the majority of popular payment 
gateways that we would want to implement for our installation, including — but not 
limited to—the likes of the following: 


2checkout 

ePay 

Fontis 

Moneybookers 

Sage Pay (formally Protx) 
WorldPay 


We'll also find functional non-payment processing methods such as: 


Bank pre-payment 
Cash on delivery 


These modules show only a small piece of what is possible with 
development of Magento's payment methods and I hope to show 
you how to get started with building them in this chapter. Many 
more payment modules can be found online on Magento Connect 


GA (http://www. magentocommerce. com/ magent o- connect ) and it 


is worth browsing through modules under the Payment Gateways filter, 
with over 200 individual payment modules available. Looking through 
these modules and downloading some of them will allow you to discover 
how the internals work as well as what's possible with payment modules. 


Let's get started by building a base payment method, which we can build upon and 
fill in the gaps with to create our desired method. 
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Building the base of a payment method 


Here, we're going to build the base of a payment method. This is something that 
won't have a purpose, but to provide us with a base — which we can build on—to 
create our fuller featured payment method. 





It will show us what the bare bones are in order for you to be able to later go on 
and create a fully functional method later on. 


Module declaration 


We need to start by declaring our module to the system. We'll do this by creating the 
fileMagentoBook_PaymentModule.xml in/app/etc/ modules/ and filling it with the 
following XML code: 


<?xml version="1.0"?> 
<config> 
<modul es> 
<MagentoBook_ Payment Modul e> 
<active>true</active> 
<codePool >l ocal </codePool > 
<depends> 
<Mage_ Payment / > 
</ depends > 
<version>0.1.0</versi on> 
</MagentoBook_ Payment Modul e> 
</ modul es > 
</ confi g> 


A noticeable feature is that we're using the <depends ></ depends > tags, to ensure 
that this module cannot be activated or used without Mage_ Payment being activated. 
This means that if the core payment-handling module in Magento has been disabled, 
then the module will not be activated or used in any way by the system. 


Module configuration 


We're now going to move onto the configuration of our module, so that we can fit it 
into the system and make sure it works with other internal components. 


We'll create a file called config. xml in/app/code//Magent oBook/ Payment Modul e/ 
etc/ and fill it with the following XML code: 


<?xml version="1.0"?> 
<config> 
<modul es> 
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<MagentoBook_ Payment Modul e> 
<version>0.1.0</versi on> 
</MagentoBook_ Payment Modul e> 
</ modul es > 
<gl obal > 
<model s> 
<payment modul e> 
<class>MagentoBook Payment Module Model </class> 
</ payment modul e> 
</ model s> 
<resources> 
<payment module setup> 
<setup> 
<module>MagentoBook_ Payment Modul e</ modul e> 
</setup> 
<connection> 
<use>core setup</use> 
</connection> 
</ payment module setup> 
<payment module write> 
<connection> 
<use>core_write</use> 
</connection> 
</ payment module write> 
<payment module _read> 
<connection> 
<use>core read</use> 
</connection> 
</ payment module read> 
</resources> 
</ global > 
<default> 
<payment > 
<payment modul e> 
<active>0</active> 
<model >payment modul e/ payment Met hod</ model > 
<order status>l</order_ status> 
<title>Credit Card (Magento Book Payment Module) </title> 
<cctypes>AE, VI, MC, DI </cctypes> 
<payment_action>authorize</ payment _action> 
</ payment modul e> 
</ payment > 
</ default > 
</ confi g> 
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Let's back up slightly here and break parts of this configuration down, so that 
everything is clear before we continue. 


We start by defining our XML version and the module version. This version 
number is used for upgrades of the script later if database upgrades of data stored 
or table structures are needed as the script progresses over time. In practice, this 
means that if we need to make changes between versions, we can use Magento's 
built-in version-control system for modules to deploy scripts between upgrades. 
This is primarily used for executing changes, such as database structure or changes 
to the database contents between upgrades. Code-only changes between upgrades 
should be fine, without an upgrade script attachment to execute any actions: 


<?xml version="1.0"?> 
<config> 
<modul es > 
<MagentoBook_ Payment Modul e> 
<version>0.1.0</versi on> 
</MagentoBook_ Payment Modul e> 
</ modul es > 


We'll now open our <g! obal ></ global > tags for declaration of models and 
handling of database resources to the system. We'll begin by declaring our model: 


<gl obal > 
<model s> 
<payment modul e> 
<class>MagentoBook Payment Module Model </class> 
</ payment modul e> 
</ model s> 


Next, we'll declare our handling of the database resources to the system. Here, we're 
using core_setup,core_write,andcore_read as our declarations because we 
don't want to use any external database with this module. We would want to simply 
use the existing Magento database setup: 


<resources> 
<payment module setup> 
<setup> 
<modul e>MagentoBook_ Payment Modul e</ modul e> 
</setup> 
<connection> 
<use>core setup</use> 
</connection> 
</ payment module setup> 
<payment module write> 
<connection> 





[88] 





Chapter 5 





<use>core_write</use> 
</connection> 
</ payment module write> 
<payment module read> 
<connection> 
<use>core read</use> 
</connection> 
</ payment module _read> 
</resources> 
</ global > 


Now we'll set up our default configuration for this module and make sure it is 
under the payment system configuration tab in the system. We use the 
<payment ></ payment > tags here (surrounding this part of the configuration) to 
declare to Magento that this is a payment module to be added to the system: 


<default> 
<payment > 
<payment modul e> 


We've to make sure that this module isn't set to acti ve by default, when it's 
installed. We'll have to set it to 1 if we want it to automatically become active: 


<active>0</active> 
We must ensure that we're referencing the pay ment Met hod model: 
<model >payment modul e/ payment Met hod</ model > 
We'll set the default order status for new orders to processing: 
<order status>l</order status> 
We'll name our block of configurable variables in the administration: 
<title>Credit Card (Magento Book Payment Module) </title> 
Then we'll define which credit card types are available to this module: 
<cctypes>AE, VI, MC, DI </cctypes> 


The default payment action for this module is now declared. This is a choice between 
Authorize and Authorize and Capture. Authorize confirms that the payment 
method is correct and valid, whereas Authorize and Capture grabs the payment 
from the account at the same time as verification. There are two possible values for 
this tag: authorize andauthorize_capture. The differences between these two 
core functions will be explained later in the chapter. 


<payment_action>authorize</payment_action> 
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We can then close all our open tags to make sure this file is processed properly: 


</ payment modul e> 
</ payment > 
</ default > 
</ confi g> 


Hopefully this has brought us closer to understanding the payment method's 
configuration file. 


The adaptor model 


Our adaptor model is responsible for adapting the model towards a functional tool 
to be used by the system. In our case all functionality is stored within this file. 


We'll create a file called Payment Method. php in/ app/ code/!ocal/CompanyName/ 
NewModul e/ Model / and place the following code within it: 


<?php 
class MagentoBook Payment Module Model PaymentMethod extends Mage_ 
Payment Model Method Cc 
{ 
protected $ code = 'payment module'; 
protected $ isGateway = true; 
protected $ canAuthorize = true; 
protected $ canCapture = true; 
protected $ canCapturePartial = false; 
protected $ canRefund = true; 
protected $ canVoid = true; 
protected $ canUselnternal = true; 
protected $ canUseCheckout = true; 
protected $ canUseForMultishipping = true; 
protected $ canSaveCc = false; 
public function authorize(Varien_ Object $payment, $amount) 
{ 
$data = $payment->getData(); 
|* 
$data = array( 
store_id, 
customer_payment_id, 
method, 
additional data, 
po_number, 
cc_type, 
cc_number_enc, 
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cc_last4, 
cc_owner, 
cc_exp_month, 
cc_exp_year 
cc_number 
cc_cid, 
cc_ss_issue, 
cc_ss_start_month 
cc_ss_start_year 
parent _id, 
amount ordered 
base amount ordered 
shi pping amount 
base shipping amount 
method_instance) 

+ 


public function capture(Varien Object $payment, $amount) 

II Grab stored payment data array for processing 
$paymentData = unserialize($payment->getAdditionalData()) 

N function void(Varien_Obj ect $payment) 

i // actions when order is voided occur here 

ae function refund(Varien Object $payment, $amount) 


{ 


// actions when order is refunded occur here 
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Let's go over the meaning of these initial variables' set up in our payment method 


class before we continue: 


$_isGat eway Is this a payment gateway? (Uses authorize or capture 


$_ can 
$_ can 


$_can 
$_ can 


$_ can 


$_ can 





$_can 


$. 
canUseForMultishi pping 


Authorize 
Capture 


CapturePartial 
Refund 


Void 
Uselnternal 


UseCheckout 


$ canSaveCc 


methods) 


Can this module authorize? (Is the authorize function 
available?) 


Can this gateway capture payment? (Is the capture 
function available?) 


Can this module partially capture payments? 


Can this module refund payments? (Is the refund 
function available?) 


Can this module void payments? (Is the void function 
available?) 


Can this payment module appear in the Magento 
payment modules administration panel? 


Can this module show as a method in the Magento 
checkout? 


Is this module multi-shipping compatible? 


Can this module save credit card information for 
future processing? 





What this code does is that it provides a very solid base for building our payment 
method. Here, we have: 


Our class declaration and initial payment module declaration to Magento 


Our protected variables which define to Magento what the module can 
and cannot do, so that it automatically restricts how the module operates 


Four functions defining key operations of a payment method: 


° authori ze( 


° capture() 
° void{() 
° refund{() 
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Payment information storage 


The $payment model that gets passed to each of the methods in our class is 

an instance of Mage_Sales_Model _Order_Payment. Every time a payment is 
processed, the data for that payment is stored inthesales_flat_quote_payment 
table. There is anadditional data field that our module could use to store values 
for each transaction. 


Four core components 


The four core components of a payment module are key operations that can be 
defined into two blocks, as follows: 


e The processing of the payment prior to completing the sale 


e After the order has had its payment successfully authorized and captured 





its payment 








successfully processed 
e authorize() e return() 
e capture() e void() 








Let's go through both of these now and understand a little more about how the core 
operations work. 


The processing of the payment 


The processing of the payment covers the aut horize() andcapture() functions. 
Going back to our module's configuration, the <payment_action></ payment _ 
acti on> tags define which of the two functions is called, once the initial order 
has taken place. We've set this to Authorize Only, which by default which will 
callauthorize() and capture() later when we click the capture button after 
invoicing. But if we choose Authorize and Capture, then only the capt ur e( ) 
function is called. 


Our code for authorizing and capturing payment will need to be placed 
appropriately within these functions. The choice to be made between the two options 
should depend on our choice of payment gateway that we're building the module 
for. An Authorize Only approach means that payment is held until we decide to 
capture it, whereas Authorize and Capture will automatically take payment as soon 
as it is authorized. This will highly depend on the workflow that we had in mind for 
the module. 
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Let's recap on how these two functions operate under the two core options in our 
<payment_action></payment_action> tags. 


Choice 


authorize() 


capture() 





Authorize Only 


Authorize and Capture 


Authorizes the customer's 
payment method via our 
payment gateway and 

does not capture the actual 
payment. It waits for further 
processing before doing 

so. This happens when the 
order is placed and happens 
automatically. 


Isn't executed at any point. 


Once the customer is 
invoiced via Magento a 
capture button appears 
in the upper right of 
the invoice screen 
within Magento's 
administration. When 
clicked, this will then 
execute the contents 

of the function for the 
payment module the user 
has authorized through. 


This happens after the 
order has been placed 
and it happens manually. 


Automatically takes 
care of both the role 
ofauthorize() and 
capture() functionality 
at checkout immediately 
upon the order being 
placed. Note: This does 
not callaut hori ze() 
automatically; it will 
only call capture() 
which should be built to 
handle both sides of the 
functionality. 





After the order has had its payment successfully 


processed 


Thereturn() andvoid() functions are called when an administrator goes into an 
order after invoicing and clicks the Return or Void buttons in the upper right of 
the order screen. The code placed within these functions will determine how the 
payment method handles an order once these buttons have been clicked. 
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Declaring configuration options for the admin 
panel 


Now that we have a module with the required functionality and setup, we'll need to 
declare our configuration options, which appear on the payment methods page of 
the System -> Configuration menu. 





Setting up the core fields 


Create a file called system. xml in/app/code/!ocal/Magent oBook/ 
Payment Module/etc/ and start by filling it with the following XML code: 


<?xml version="1,.0"?> 
<config> 
<sections> 
<payment > 
<groups> 
<payment module translate="label" module="paygate"> 
<label >NewPayment Modul e</label > 
<sort_order>670</sort_order> 
<show_in_default>1l</show_in_default> 
<show_in_website>l</show_in_website> 
<show_in_store>0</show in store> 
<fields> 
{afi elds} 
</fields> 
</ payment modul e> 
</groups> 
</ payment > 
</sections> 
</ confi g> 


Replace {..f i el ds...} with the following fieldset XML code: 


<active translate="label"> 
<label >Enabl ed</| abel > 
<frontend type>select</frontend type> 
<source model >adminhtml/systemconfig source yesno</source model > 
<sort_order>l</sort_order> 
<show_in_default>1l</show_in_default> 
<show_in_website>l</show_in_website> 
<show_in_store>0</show in_store> 

</active> 

<order status translate="label "> 
<label >New order status</label > 
<frontend type>select</frontend type> 
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<source model >adminhtml/system config_source order status processing 
</source_ model > 
<sort_order>4</sort_order> 
<show_in_default>1l</show_in_ default > 
<show_in_website>l</show_in_website> 
<show_in_store>0</show in _store> 
</order_status> 
<title transl ate="label'"> 
<label >Title</label > 
<frontend type>text</frontend type> 
<sort_order>2</sort_order> 
<show_in_default>1l</show_in_default> 
<show_in_website>l</show_in_website> 
<show_in_store>0</show in_store> 
</title> 


As you can see in the XML, it does not matter which order you place the fields in. 
Only thesort_order field name will be used when deciding the order of the fields 
on output in the section of the Magento administration. 


This would create three base fields for the module, as follows: 








Field name What it would be used for 
Enabled To turn the module on/off within the system 
New order status Gives us the ability to choose Authorize Only or 


Authorize and Capture 
Title The title of the module when presented to the user 





These three fields are a suggested base for the module in order to control the very 
basics of our payment module. It's a suggestion to enable control of whether or not 
the module is enabled, the new order status, and the title of the module itself on the 
frontend when presented to the user as a form of payment method they can choose 
on checkout. 


If we go to System->Configuration and choose Payment Methods from the sidebar 
menu, we would see a New Module group of configurable options for our module. 
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Some other field types you can use 


There are numerous other fields that we can setup for our module which can be 
grabbed from pre-existing modules in Magento at the moment. These come in handy 
as we won't need to set them up ourselves and they slot in easily. A typical field 
setup is as follows: 


<title translate="l abel "> 
<label >Ti tl e</label > 
<frontend type>text</frontend type> 
<sort_order>2</sort_order> 
<show_in_default>1l</show_in_default> 
<show_in_website>1l</show_in_website> 
<show_in_store>0</show in _store> 

</title> 


In our scenario the <f rontend_type></frontend_type> tag pair is the most 
important tag pair, as this is the only value we change when pre-populating field 
types. The following are examples of values which can be placed inside these tags 
to produce different fields: 


£ 


e adminhtml/system_config_source_yesno—returns yes or no for you 


field type 
e adminhtml/system config source order _status_new—returns an 
array of options for use when selecting a new order's status 


e adminhtml/system config source email identi t y—returns a list 
of email identities in the system from which to send emails from 


e adminhtml/system config source email temp! at e—returns a list 
of email templates in the system from which to send emails with 

















e adminhtml/system config source payment _cctype—returns a list of 
credit card types, useful for multi-selects when deciding the types of cards 
that we would want our module to accept 


We'll have a look at the file /app/code/core/Mage/ adminht ml / Model / Syst em/ 
Config/ Source. php to see all the options available to us as source models. 
This could potentially unveil some additional options that will benefit us in our 
module development. 
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Obscuring fields 


We could use the following pair to obscure data in the backend and reveal the data 
when it placed back into the field on its way out of the database: 


<frontend type>obscure</frontend type> 
<backend_ model >adminhtml/system.config_backend encrypted 
</backend_model > 


This would, of course, be placed within our standard field tag. Take the following 
example from Google Checkout's setup: 


<merchant_id transl ate="label"> 
<label >Merchant | D</l abel > 
<frontend type>obscure</frontend type> 
<backend_ model >admi nhtml/system_config_backend encrypted 
</backend_model > 
<sort_order>20</sort_order> 
<show_in_default>1l</show_in_default> 
<show_in_website>l</show_in_website> 
<show_in_store>0</show in_store> 

</merchant_id> 


The backend_model makes sure it is encrypted when put into the database and the 
frontend_type means that it's unencrypted on the way back out. 


Custom fields from our models 


We can create our own field population source models by making use of the Model s / 
directory. Take the following example from the Google Checkout module's / ap p/ 
code/core/Mage/ Googl eCheckout/etc/system. xml file: 


<checkout_image translate="label"> 
<label >Checkout Image Style</label > 
<frontend type>select</frontend type> 
<source model >googl echeckout/source checkout _i mage</source model > 
<sort_order>40</sort_order> 
<show_in_default>1l</show_in_default> 
<show_in_website>l</show_in_website> 
<show_in_store>0</show in_store> 
</checkout_image> 
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This calls the model / app/ code/ core/Mage/ Googl eCheckout/ Model / Source/ 
Checkout/1! mage. php and the inner function t 00pti onArray() .This returns the 
values to Magento, which handles the output into the Magento administration. 
Take a read of the file should you be interested in digging further into how they 
make it work. 


Tying in automatic shipping tracking/updating 
The following is an example of payment methods offering a specialized feature in 
hooking up shipping integration. Hopefully, we should be able to take something 
from this and be able to either re-apply these methods within our payment modules 
or apply similar methods in our custom modules built for Magento. 


Automatic shippingtracking and 
code-generation tie-in 


Amazon Payments has a setup due to which, if we mark an item as shipped or 
update the tracking code for that order, then it will report the codes and the status 
of the order for tracking in their system back to Amazon. 


This is useful in several ways: 


e It helps the user stay in the loop without coming to the website 


e The user somewhat expects this to happen if their payment gateway that 
they are paying through provides this as functionality with other websites 


e This then, of course, helps them relate to our brand more and gives them the 
unexpected surprise that makes them come back or talk about the site more 


This is done via observation on events in the system. The two events that the module 
observes and then acts upon are: 


e The confirmation of an order shipment 


e The saving of a tracking shipping number to an order 


If the/ app/ code/core/Mage/AmazonPayments/etc/config.xml file is opened 
in default installation of Magento, we'll see the following code that defines the 
observers in the system between <admi nht ml ></ admi nht ml > tags: 


<events> 
<sales_order_shipment save _after> 
<observers> 
<amazonpayments > 
<type>model </type> 
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<class>amazonpayments/observer</class> 
<method>confirmShi pment </ met hod> 
</amazonpayments> 
</observers> 
</sales_order_ shipment _save_ after> 
<sales_ order shipment track _save_after> 
<observers> 
<amazonpayments > 
<type>model </type> 
<class>amazonpayments/observer</class> 
<method>salesOrderShi pmentTrackSaveAfter</ met hod> 
</amazonpayments> 
</observers> 
</sales_order_shipment_track_save_after> 
</events> 


This XML information and set of fields defines the observers so that information is 


passed to a set type of class and method for processing. Take the second definition 
for example: 


<sales_order shipment track _save_after> 
<observers> 
<amazonpayments > 
<type>model </type> 
<class>amazonpayments/observer</class> 
<method>salesOrderShi pmentTrackSaveAfter</ method> 
</amazonpayments> 
</observers> 
</sales_order_shipment_track save _after> 


This makes sure that when a sales order shipment tracking code is saved, directly 
afterwards the AmazonPay ments module will look for: 
e Something in the / model / folder of (defined in the <t ype></ t ype> tag pair) 


e TheAmazonPayments module called Observer. php (defined in the 
<class></class> tag pair) 


e ThesalesOrderShi pment TrackSaveAfter() method within this file 
(defined in the <met hod></ met hod> tag pair) 
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On the other end of these observers is the model file itself (Observer. php) that sits 
within the / model / folder of the AmazonPay ments module folder. If we go to/ app/ 
code/core/Mage/AmazonPayments/ Model/ Observer. php we'll see the code for the 
methods that are on the other end of these observers that are set: 


class Mage AmazonPayments Model Observer 
{ 
public function confirmShipment(Varien_Event Observer $observer) 
{ 
$shipment = $observer->getEvent()->getShipment(); 
if ($shipment->getOrder()->getPayment()->getMethod() != 
‘amazonpayments cha') { 
return; 
} 
Mage::getModel('amazonpayments/api_cba') 
->confirmShi pment ($shi pment); 
} 
public function salesOrderShipmentTrackSaveAfter(Varien_Event_ 
Observer $observer) 
{ 
$track = $observer- >getEvent()->getTrack(); 
$order = $track->getShi pment()->getOrder(); 
/* @var $order Mage Sales Model Order */ 
if ($order->getPayment()->getMethod() != 'amazonpayments cha') { 
return; 
} 
Mage::getModel('amazonpayments/api_cba') 
->sendTrackingNumber($order, $track); 
} 
} 


There are a few key areas to pick up upon here that are important when replicating 
this functionality in your own modules. Let's go through a few certain key blocks to 
ensure we're benefiting from reading this code. 


We start by noticing that Varien_Event_Observer $observer is the only variable 
being caught within both of these functions. This is how observers are setup and 
work with the system to properly process the event they are observing. A notable 
aspect is that these functions are public, and not private. 


public function confirmShipment(Varien_Event Observer $observer) 


{ 
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Next, we've got a block of code for ensuring that the payment method used for this 
order is actually Amazon Payments CBA. This is important, as Amazon Payments 
doesn't need to hear about orders placed through other payment gateways. This is 
vital to ensuring smooth integration of the payment module. If the payment method 
isn'tamazonpayments_cba then we can simply return nothing and let Magento carry 
on as usual through the other observers waiting for this action to occur. 


$shipment = $observer->getEvent()->getShipment(); 
if ($shipment->getOrder()->getPayment()->getMethod() != 
‘amazonpayments cha') { 

return; 


} 


It's also important to notice the code separation going on here. The observer class 
is only used for receiving notification of the event. All actual executed code is in 
external models that are built for the next step. We can see how they've included 
an external model here: 


Mage::getModel('amazonpayments/api_cba') 
->confirmShipment($shi pment); 


The last thing to notice from the functions at hand is the way they gather 
the shipping, tracking, and order information and how they make use of the 
$observer class. 


$shipment = $observer->getEvent()->getShipment(); 
And in the second function within the class: 


$track = $observer- >getEvent()->getTrack(); 
$order = $track->getShi pment()->getOrder(); 


These methods could be used in our observer classes if we wish to place them 
within our built payment modules. 


To see how the objects created by those three functions are processed, open the file 

/app/code/core/Mage/ AmazonPayments/ Model /Api/Cba. php and search for the 

functions that the two observer functions execute from this file when looking to the 
executable action of the observation they were there to observe: 


e confirmShi pment 


e sendTrackingNumber 


These two functions teach us a lot about how to learn more about those three 
variables created and passed to the functions. They also elaborate on how the 
three variables are used when passed through to the resulting function. 
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We'll also see the same two observers across other bundled payment gateways such 
as Google Checkout, which should be explored for further depth of information on 
the topic. 


Summary 


In this chapter, we learned the following: 


e Which payment methods are bundled with Magento by default 


e The popular payment methods that can be downloaded from Magento 
Connect 


e How to put together the basics of a payment method for Magento and 
the core functions Magento uses automatically from the methods it uses 


e How to setup the fields as well as how to obscure and encrypt them 


e How to link in our own pre-populated arrays of field values from our 
custom models 


e Tying in automatic shipping-tracking code generation and updating into 
our payment module 


Further, we should research the other payment methods available on Magento 
Connect. These will help us learn more about how payment methods are structured 
and function internally. When we try to create functionality for us, we will learn in 
depth about the existing payment methods. 


We should also be able to create our own payment methods for our Magento 
installations that need them. 
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Building a Basic Featured 
Products Module 


In this chapter, we will learn how to put together a basic module in Magento. 

This module will allow us to feature products on the site and within our product 
categories. This will introduce us to some of the basics of module development in 
Magento and enable us to form a fundamental base for future module development. 


One of the most implemented features on a Magento site is the ability to feature 
products. Whether it is the home page, or the sidebar, or the footer, featured 
products are a fundamental building block of an e-commerce website. Typically this 
is done through banner advertising, but with this module we'll use the products 
themselves as a base for our information. We'll display product blocks on the 

site using this featured product data, gathered dynamically in the administrative 
backend of Magento. 


How it works 


To make this happen, we'll set up an attribute in our system to mark a product as 
featured and then create a bespoke module that will allow us to display products 
marked as featured on a per category basis. 


The process for getting a product to appear in the Featured Product block will go 
as follows: 

e Create or edit a product 

e Find the field featured and select yes from the dropdown 

e Save the product information that we have changed or created 


e Go toa category that this product is assigned to and it will appear 
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To build our module we will: 


e Create the attribute 


e Create our module with the core functionality 


e Extend the category view to include our featured product display 


e Create templates for display 


e Define the module in our! ocal. xml module configuration file 


e Add in our XML block declaration, so that the module displays on 


the frontend, and get started 


Creating the attributes in the system 


We'll start by going to Catalog -> Attributes -> Manage Attributes from within 


the administration. 


Magento Admin Panel 


| Dashboard Sales 


Dashboard 


Attributes 


Search 


Tags 


Catalog Customers 
Manage Products 





Promotions Newsletter 


Manage Categories 


Manage Attributes 
Url Rewrite Mar- ------s-.es.rsisiss sosenem 


anage Attribute Sets 





£ Reviews and Ratings 


EZE coo base 


£ Google Sitemap 


orgs rm ouNntsS 











Next, we'll click on Add New Attribute in the upper right of the Manage 


Attributes screen. 








© Add New Attribute 
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The New Product Attribute screen is shown in the following screenshot: 





Attribute Information @ New Product Attribute J eck | EE 
Properties E] 
Manage Label / Options 
Attribute Code * featured For internal use. Must be unique 


with no spaces 


Scope Store View $ Declare attribute value saving 
scope 

Catalog Input Type for Yes/No $ 

Store Owner 

Default value No $ 

Unique Value No $ Not shared with other products 

Values Required No $ 

Input Validation for Store None ry 

Owner 

Apply To * All Product Types A 

Frontend Properties 

Use in quick search No s 

Use in advanced search Yes : 

Comparable on Front-end No $ 

Use In Layered Navigation No : Can be used only with catalog 
input type Dropdown, Multiple 
Select and Price 

Use In Search Results No g Can be used only with catalog 

Layered Navigation input type Dropdown, Multiple 


Select and Price 











Setting the field values 


We'll set the fields on this page as follows, to set up our Featured Product attributes 
in the system. 


Attribute Properties 


The properties of each attribute from the previous screenshot is given below: 








Field name Field value 
Attribute Code featured 

Scope Store View 
Catalog Input Type for Store Owner Yes/No 

Default Value No 

Unique Value (not shared with other products) No 

Values Required No 

Input Validation for Store Owner None 

Apply To All Product Types 
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Frontend Properties 


The Frontend Properties are described as follows: 








Field name Field value 
Use in quick search No 

Use in advanced search Yes 
Comparable on Front-end No 

Use In Layered Navigation (it also refers to No 
Multiple Select and Price.) 

Visible on Product View Page on Front-end Yes 


al 


` Ignore all other attributes that appear and leave 
them as their default values 


Manage Label/Options 


This is found by clicking on the Manage Label/Options tab on the left-hand side 
of the current page. 


We chose Featured Product as our label for this attribute when displayed. 
However, we can replace this field value with another one, if we want something 
else to appear. 





Field name Field value 
Admin Featured Product 








The Manage Label/Options tab will look something like this: 





Admin English French German 
Featured Product 











We must remember to save our attribute to complete this section of the chapter. 


Following this you will need to go to Catalog -> Attributes -> Manage Attribute 
Sets. Once here select your chosen attribute set that you'd like to add this new 
featured attribute into. You can repeat this step multiple times, should you want to 
for each attribute set that you'd like to add the attribute to. 
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[9 Manage Attribute Sets 


Page 1 of1 pages | View [20 $) perpage | Total 14 records found ly ES 


Set Name 


Cameras 
Cell Phones 
Computer 
CPU 
Default 
Furniture 
Hard Drive 
Monitors 
RAM 

Shirts (General) 
Shirts Other 
Shirts T 
Shoes 
Warranties 











I've chosen to select Default in this example. 


You should see the attribute that we've created under Unassigned Attributes on 
the right hand side of the screen that now appears. 





Unassigned Attributes 


=] featured 











Proceed by clicking and holding your mouse down to drag and drop the featured 
attribute into the attribute group of your choice in the middle. 
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You should now see something along the lines of the following with the featured 
attribute under the group: 





=| General 
Egname 
=] featured 
Ed sku 
Egweight 
Eg status 
E4 tax_class_id 
Egurl_key 
Ea visibility 
= dgift_message_available 
=] manufacturer 
=] color 
Ed news_from_date 
= news_to_date 














Creating the core module with functionality 


We'll now create the function that allows us to present the products that are featured 
to our block, for displaying them to the end user. The class that we created contains 
the function that expands existing Magento catalog functionality. This occurs so that 
we can interact with other catalog functionality directly and integrate directly with 
the existing class files. 


We'll create the file Feat ured. php and the directories to create the path: app/ code/ 
local /MagentoBook/Catalog/Block/Product/ Featured. php. 


For adding functionality, we'll edit the newly created Feat ured. php file and place 
the following in it: 


<?php 
class MagentoBook Catalog Block Product Featured extends 
Mage_ Catalog Block_Product_Abstract 

{ 

protected $ limit = 1; 

public function getFeaturedProducts{() 

{ 

$productCollection = Mage::registry('current_category')- 
>getProductCollection(); 
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Mage::getModel('catalog/layer')->prepareProductCollection 
($productColl ection); 

$productCollection 
->addAttributeToFilter('featured', true) 
->setPageSize($this->_limit) 
->load(); 

return $productColl ection; 


} 

public function setLimit($limit = null) 

{ 

if(intval($limit) > 0) 
$this-> limit = intval($limit); 

} 
} 
?> 


Let's break this down, so that we fully understand the contents of the file. 


First, we'll declare the class, which will extend the core Mage_Catal 0g module to 
integrate directly into the system and allow us to interact with core functionality 
that we need in order to create this module: 


<?php 

class MagentoBook_Catalog_Block_Product_Featured extends 
Mage_Catalog_Block_Product_Abstract 

{ 


We'll then set up the $_1 i mi t variable, which will hold the number of featured 
products that are to be fetched: 


protected $ limit = 1; 


Next, we'll declare get Feat uredProducts with which we will grab the featured 
product for the current category: 


public function getFeaturedProducts() 


{ 


We'll build $product Collection result by building a base line query for get 
products for current category: 


$productCollection = Mage::registry('current_category')- 
>getProductCollection(); 

Mage::getModel('catalog/layer')->prepareProductCollection 
($productCollection); 
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We'll then add filters to make sure that we only select where the Featured attribute 
is set to true (or Yes) and limit the results to the amount stored in the variable 
(which we set earlier in the class). 


$productCollection 
->addAttributeToFilter('featured', true) 
->setPageSize($this->_limit) 
->load(); 


This is then returned for usage in the template file of the module's output: 


return $product Collection; 


} 


We will end the file with the set Li mi t function, which allows us (or anyone using 
the module) to override the output limit: 


public function setLimit($limit = null) 


{ 
if(intval($limit) > 0) 
$this-> limit = intval($limit); 
} 
We'll end our class declaration and our file: 
} 
?> 


That completes the class file of our module! 


Adding the XML block declaration for display 


of the module on the frontend 


We'llopen/app/design/frontend/default/default/layout/catalog. xm. 
We want to add a new <b! 0ck> right above the Product List block in the Default 
Category layout. 


We'll search for the <cat alog_category_defaul t > tag and the content within it. 
Once we've found this, we have two choices as to where we can place our featured 
content block, The choices are <ref erence name="left">and<reference 
name="content" >, which both relate to the left sidebar of our layout and the content 
layout. We can also add other references between these tags, if the layout requires it. 
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Once we've chosen the relevant reference tag, we add in the following block to call 
our module that we have put together every time the category page loads: 


<block type="catalog/product_featured" name="product_ featured" 
as="product_featured" 
template="catalog/product/featured. phtml"></block> 
<block type="catalog/product_featured" name="product_ featured" 
template="catalog/product/featured. phtml"> 
<action method="setLimit"><limit>2</limit></action> 
</ block> 


The template address catalog/product/featured. pht m , can be replaced with 
whatever custom file we want, if we wish to separate the template out from the 
existing set that comes with Magento's default frontend theme. 


It's worth noting that the following code sets how many products should be returned 
by the template: 


<action method="SetLimit"><limit>2</limit></action> 


With the code we've just inserted, two featured products will output. To change, 
simply switch the number '2' for the number of products you'd like to output in your 
template files. 


The product_featured return statement from our previous section in putting 
together the module is featured here. Imagine this block as the part where Magento 
requests product_featured and the Vi ew. php file that we built above as the part of 
our module that returns the appropriate content. 


Creating templates for display 


In order for our module to appear, we need our templates to call the function that 
we've created at some point. In this case, we presume that we've gone with the 
choice of <ref erence name="cont ent" > and include the featured block in the 
content area of our layout. 


We'll open up the Vi ew. pht ml file located at/app/design/frontend/default/ 
default/template/catalog/category/ View. phtml and add the following code 
above the first occurrence of <?php echo $this->getProductListHtml(); ?>in 
this template file: 


<?php echo $this->getFeaturedProductHtml(); ?> 
<?php echo $this->getChildHtml('product_featured'); ?> 
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This will place our Featured Product content block above the place where products 
are output. 


We'll now need a physical template file for our featured product block, in order for 
it to display our featured products. To do this, we'll create featured. pht ml (if it 
doesn't exist already) at the location/ app/design/frontend/default/default/ 
templ ate/catalog/product/featured. phtml and place some code within it to 
present our featured products out onto the website. 


Here is an example that shows (in code order): 


e The name of the product linked to its individual product page 
e Its image at a 200 x 200 size 


e An Add to Cart button for the user to add it into their cart directly from 
where it is displayed 


e A check to see if the item is out of stock or not before displaying the Add 
to Cart button, with a warning message if it is in fact out of stock 
<?php 
foreach($this->getFeaturedProducts() as $ product): ?> 
<form action="<?php echo $this->getAddToCartUrl($ product) ?>" 
method="post" id="product_addtocart_form'> 
<a href="<?php echo $_product->getProductUrl() ?>"> 
<?php echo $this->html Escape($_product->getName()) ?></a> 
<img class="product-image" src="<?php echo 
$this->helper('catalog/image')->init($_product, 'small_image')- 
>resize(200, 200) ?>" alt="<?php echo $this 
->ht ml Escape($_product->getName()) ?>" /> 
<?php if($_product 
->isSaleable()): ?> 
<button class="form-button" onclick="setLocation 
(' <?php echo $this->getAddToCartUrl($_product) ?>')"> 
<span><?php echo $this->__('Add to Cart') ?></span></button> 
<?php else: ?> 
<div class="out-of-stock"><?php echo 
g$this->__('Out of stock') ?></div> 
<?php endif; ?> 
</form> 
<?php endforeach; ?> 
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Defining the module in the local .xml module 
configuration file 


Now that everything is in place, we need to ensure that our module is declared 
to Magento by including it in our! 0ca!l. xml file. We can find this file in the 
/app/etc/ directory. 





We'll add the following inside the <confi g></ confi g> global tag pair that 
surrounds all inner declaration tags: 


<bl ocks> 
<catalog> 
<rewrite> 
<product_featured>MagentoBook Catalog Block _Product_Featured 
</product _featured> 
</rewrite> 
<rewrite> 
<category_view>MagentoBook Catalog Block Category View 
</category_vi ew> 
</rewrite> 
</catal og> 
</blocks> 


Once this is done, our Featured Products module will be included in the system. 
We do not need to activate/ deactivate the module, as it extends a core component 
of Magento and for this reason does not need to be declared separately. 


This concludes adding a featured product section into your Magento 
category templates. 


Summary 


In this chapter, we've learned: 


e How to put together a basic module in Magento 


e How to create a featured product attribute which allows us to feature 
products by which category the user is currently browsing 


We must continue developing these modules further to fit our specific needs, to 
extend other parts of Magento's core modules, and to integrate what we've learned 
in this chapter into our Magento implementations. 
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Magento with Admin Panel 


In this chapter, we'll go through the basics of module development, right from 
getting a simple Hello World message displayed to managing the module's 
information in the database and making it into a dynamic extension of Magento. 
This extension will be used to manage the output of brands on a page that will be 
displayed on the frontend of our installation. 


We'll go through: 


Getting the module set up using a pre-built module creation tool 

Getting our first Hello World displayed on the frontend 

The overall structure of where files should go and what structure to use 
How all the files of the module are put together and what each of them does 
Extending the result into a brand management module 


Displaying the managed results data on the frontend of our 
Magento installation 


We'll start by assembling the basic structure and the files needed to get a Hello 
World message displayed and proceed ahead to upgrading the module to bring in 
additional elements. These will include an administration panel and dynamic output 
to Magento. It will also include giving the module its own unique URL within the 
installation. It provides our module with a dynamic frontend, using which visitors 
can browse through the data that is managed in the backend. 
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Creating our first Hello World message 


We'll start with a quick Hello World via a display block. This process is more 
complex than displaying a message directly, but it shows us the fundamentals of 
what we'll be trying to achieve in this chapter. With the exception of simply typing 
Hello World in an existing template block, this is the quickest way of getting our 
own template block into Magento's display system. 


Setting up the display template 
We'll start the process by setting up the template itself with our Hello world 
statement inside of it. 


First, we'll create the directory /app/design/frontend/default/default/ 

templ ate/hello/ and create/place the file wor! d. pht ml within it. Hence, the full 
address should be/ app/design/frontend/default/default/templ ate/hello/ 
world. phtml. 


Next, we'll insert our Hel | o World text within the file: 
<h2>Hello World! </h2> 


We've placed an <h2> tag on either side of the statement so that it stands out 
on screen. 


Placing the display template in a layout 
.xml file 


Now that we have our display template, we need to ensure that the layout block 
appears ona layout. xml file, so that it can be output on the site. 


We'll place the following block of code in the layout. xml file of our choice: 


<block type="core/templ ate" name="helloworld" templ ate="hello/world. 
pht ml" /> 


For example, we'll take the core. xml file, which contains the following by default: 


<?xml version="1,0"?> 
<layout version="0.1.0"> 
<default> 
<block name="formkey" type="core/template" templ ate="core/ 
formkey.phtml" /> 
</ default > 
</| ayout > 
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Let's place our layout block within the XML file and ensure that it appears correctly 


within the reference name in our layout, in the right-hand column: 


<?xml version="1.0"?> 
<layout version="0.1.0"> 


<default> 


<block name="formkey" type="core/template" templ ate="core/ 


formkey.phtml" /> 


<reference name="ri ght"> 


<block type="core/templ ate" 


world. phtml" /> 


</reference> 





</ default > 
</ layout > 


name="helloworld" template="hel| o/ 


After we've saved these files, our Hello world! message will be displayed in the right 


sidebar, as shown below: 








% MY CART 


You have no items in your 
shopping cart. 


=| COMPARE PRODUCTS 


You have no items to compare. 


Hello world! 


BACK TO SCHOOL 


Keep your eyes open 


for our special Back 
to School items 
and save BIG! 











As we can see, the Hello world! message is displayed between Compare Products 
and BACK TO SCHOOL advertisement. 
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Creating our first /helloworld/ URL 
structure 


Another step into Magento module development is to create a complete module that 
becomes a section of the site via having a URL of its own. We're now going to create 
one of these modules to get ourselves a/ he! | owor | d/ URL structure and a section 
of the site dedicated to our created module. 


First, we need to put together the module's structure before adding the URL. This is 
so that we're set-up going forward. Should you want to just have the URL for your 
module, you only need to follow the last step of this section in the chapter. 


The directory structure 


We'll create and set up folders to match the following directory structure in 
preparation for putting together the module for the rest of this chapter. 


The directories for the module's core files need to be set as follows: 


e /app/code/local/Book/ Hel! oworl d/ 


° Block/ 

° controllers/ 
2 e0 

° Helper/ 

° Model / 

° Mysql 4/ 


° Hell oworl d/ 
° sql! 
°  helloworld setup/ 


For the module's design template files: 
e /app/design/frontend/default/default/ 


° template/ 
° hell oworl d/ 
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Giving the module a backend 


Now that we have our directory structure in place, we'll need to create a configuration 
file which makes sure that Magento can view our module in the system. 


The file / app/etc/ modules/ Book Hell oworld. xml should be created for our 
module and should contain the following: 


<?xml version="1. 0"?> 
<config> 
<modul es> 
<Book_ Hell oworl d> 
<active>true</active> 
<codePool >l ocal </codePool > 
</Book_ Hell oworld> 
</ modul es > 
</ confi g> 


The module will now appear in the Disable Modules Output section under 
System->Configuration, then Advanced under the left sub-menu. We can either 
disable or enable this module through this menu. 


Note: If the module does not appear on the page, then we'll need to clear the 
Magento installation's cache. To do this, we should go to System->Cache 
Management in our backend menu, select Disable from the drop-down to 
the right of All Cache, and click Save cache settings. 


-a 
Ka 


Configuring the module 


Every module requires a config. xml file to set it up. In this case, we'll set up a very 
basic version of the file (and nothing more) to get the module up and running. Later 
on this file becomes very important in making the module dynamic and we'll extend 
it much further than this base. 


We'll create the file / app/code/local/Book/Helloworld/etc/config.xml and fill 
it with the following: 


<?xml version="1.0"?> 
<config> 
<modul es > 
<Book_ Hell oworld> 
<version>0.1.0</version> 
</ Book_Hel | oworl d> 
</ modul es> 
<frontend> 
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<routers> 
<hel | oworld> 
<use>standard</use> 
<args> 
<module>Book_ Hel! oworl d</ modul e> 
<frontName>hell oworld</frontName> 
</args> 
</hel | oworl d> 
</routers> 
<l ayout > 
<updates> 
<hel | oworld> 
<file>helloworld. xml </file> 
</ hell oworl d> 
</updates> 
</ | ayout > 
</frontend> 
<gl obal > 
<bl ocks> 
<hel | oworld> 
<class>Book_ Helloworld_ Block</class> 
</helloworl d> 
</blocks> 
<hel pers> 
<hel | oworl d> 
<class>Book_Helloworld Helper</class> 
</ hell oworl d> 
</hel pers> 
</ global > 
</ confi g> 





We'll break the code down and go through each tag individually. 


We'll start by defining the <c onf i g> tag and the XML header for the file: 


<?xml version="1.0"?> 
<config> 


We'll follow it up with the declaration of our module and defining our module 
version number: 


<modul es> 
<Book_Hell oworl d> 
<version>0.1.0</version> 
</Book_ Hell oworld> 
</ modul es > 
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Opening the <f ront end> tag, here we'll be setting up the module's URL; the 
<frontName> tag defines the URL, via which the module will be directly accessed. In 
our example, we've used he! | owor | d, as we want to achieve a/ hel | oworl d/ setup. 


<frontend> 
<routers> 
<hell oworl d> 
<use>standard</use> 
<args> 
<module>Book_ Hell oworl d</ modul e> 
<frontName>hell oworld</front Name> 
</args> 
</ hell oworl d> 
</routers> 


We'll continue inside the <f r ont end> tag to define the layout. xml file attached 

to this module. These are the XML blocks that will be processed once the module 

is accessed directly via the f r ont Name value we set in the tag above. In this case, 
when / hel! | oworl d/ is accessed by a user, the layout. x ml file will be accessed to get 
module-specific blocks to load. This is followed by the closing of the <f r ont end> tag, 
as it concludes our module's frontend configuration tags. 


<l ayout > 
<updates> 
<hel | oworl d> 
<file>helloworld. xml </file> 
</ hel | oworl d> 
</updates> 
</|l ayout > 
</frontend> 


The module's display block models are next. Here, we're declaring that this module 
has a display block model class, which lets us use this model as display block types 
in Magento's. xml layout files. 


<gl obal > 
<bl ocks> 
<hell oworld> 
<class>Book_Helloworld Block</class> 
</hel | oworl d> 
</blocks> 
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Continuing with the <gl obal > tag, we'll define our Hel per model for the module, 
so that it is available to the blocks when they are used. This is then followed by the 
closing of the module's <gl obal > tag: 


<hel pers> 
<hell oworld> 
<cl ass>Book_Helloworld_Hel per</class> 
</hel | oworl d> 
</hel pers> 
</ global > 


We'll close the <c onf i g> tag to end the file and that finishes everything: 
</ confi g> 


We now have aconfig.xml file for our module. 


Our controller 


The module's controller will take in the direct URL and process the layout attached 
to it. Later on it will be responsible for loading the data to the index of our module, 
when accessed via/ hel | owor l d/ . At the moment however, it will load just the 
<def aul t > tag from our layout. .xml file (which we'll set up later). 


We'll create the file / app/code/!local/Book/Helloworld/controllers/ 
| ndexController. php and fill it with the following: 


<?php 
class Book _Helloworld_IndexController extends Mage Core Controller_ 
Front Action 


{ 


public function indexAction() 
{ 
$this->loadlLayout(); 
$this->renderLayout(); 
} 
} 


There are two core functions to this controller: the first loads the module's layout 
. xml file and processes it: 


$this->loadLayout(); 


The second function renders this layout using the blocks defined in the layout 
. xml file and outputs it: 


$this->renderLayout(); 








[124] 


Chapter 7 





The Helper model 


Not every module uses a Helper model, but we'll be working on one anyway (for 
illustrating this chapter). We'll be learning about the best practices for using them 
in our module. Typically, a Helper model will be utilized for its helper functions, 
which are used for formatting or altering output in some way. Examples of that are 
as follows: 


e Number formatting (currency, number rounding into thousands) 


e Alternative row color/class outputting 


We'll create the file / app/code/|ocal/Book/Helloworld/ Hel per/ Data. php and 
place the following code within it: 


<?php 


class Book_Helloworld_Helper_Data extends Mage Core Helper Abstract 
{ 
} 


At the moment the file is empty in order to set it up for later editing. We will place a 
function or two in the Helper model later for usage. 


The module's default model 


All modules have a default model that is attached to them. The default model 

is responsible for fetching the data and/or setting it up for the module's design 
template files to process through. It is called when we declare a block, for example 
type=hello/world on a display block would call the wor | d function inside the 

Hel | o model. 


We'll create the file / app/code/|ocal/Book/Hel!loworl d/ Model / Hell oworld. php 
and place the following code within it: 


<?php 


class Book_Helloworld Model Helloworld extends Mage Core Model _ 
Abstract 
{ 
public function _construct() 
{ 
parent::_construct(); 
$this->_init('helloworld/helloworld'); 
} 
} 
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This sets up the model for the module and initializes the model's functions for usage 
in any template. xml file once we have some blocks. 


Template blocks and display 


Now we'll need to create the frontend for our module and make sure that Magento 
has something to output, when our module's chosen URL/ he! | oworl d/ is accessed 
by a user. 


Display block class 


This holds the functions for the display block to refer to and is needed for our 
template . xml file to pass the messages across. 


We'll create the file / app/code/|ocal/Book/ Hel! oworl d/ Bl ock/ Hell oworld. php 
and place within it the following: 
<?php 
class Book_Helloworld_Block_Helloworld extends Mage_Core_Block_ 
Template 


public function _prepareLayout() 


{ 


return parent:: preparelayout(); 


public function getHel!l oworl d() 


{ 


return ‘Hello world'; 
} 
} 


We can see that we have a get Hel | owor! d function, which will return the Hello 
world! message to our template file. 


The layout .xml file 


Our module needs a dedicated layout. xml file, in order to load the display blocks 
for our module when it is accessed. 


For that, we'll create the file/ app/design/frontend/default/default/!ayout/ 
hell oworld.xml and place the following within it: 


<?xml version="1.0"?> 
<layout version="0.1.0"> 
<helloworld_index_index> 
<reference name="content"> 
<block type="helloworld/helloworld" name="hell oworld" 
template="helloworld/helloworld.phtm" /> 
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</reference> 
</ hell oworld_index_index> 
</ layout > 


The design template file 


Finally, we have our design template file which will be used for formatting the 
output from the display block model. 


We'll create/app/design/frontend/default/default/templ ate/ Hell oworl d/ 
helloworld. phtml and place the following inside it: 


<h2><?php echo $this->getHelloworld(); ?></h2> 


This will return the get Hel | oWorld() function from our display block between a 
pair of <h2> tags. 


Viewing /helloworld/ 


Now that we've put everything together that's required, we have our first display 
block powered Hello World!. Accessing / hel | owor l d/ displays something along 
the lines of the following, depending on our theme: 


Search entire store here.. Search 


M Magento 


Demo Store 


Your Language: | English h$ 





Furniture Electronics Apparel 


K Hello World! ty MY CART 
Did you know? 3 
Our customer service is jalen a st 
available 24/7 
(555) 3550123 A pnogliGrs 


Hold on, help is 
on the wa 


r+ 


You have no items to compare. 





Hello world! 


BACK TO SCHOOL 

© POPULAR TAGS — Keep your eyes open 
for our special Back 

Camera Hohoho SEXY Test to Schooli 











apple bones COO! coot-shit crap and save BIG! 
acos green hip laptop 
notebook phone red tight young 








n fice 
n 





g COMMUNITY POLL 


View Ail Taos 
What is your favorite Magento 
NEWSLETTER feature? 
Sign up for our newsletter: - Layered Navigation 
>) Price Rules 
_) Category Management 


=o i Guapen Pat 
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Taking a look at what we've put together 
Let's go over all the work that we've just done to create this module and get to 
this point. 


We have created: 


e A directory system that holds our module and all its files 

e Asystem configuration file to declare our module to the system 

e A module configuration file to declare our module's configuration 

e A controller which processes the request when the user loads / he! | owor! d/ 
e A default model 

e A helper for functions to help out with formatting in display templates 

e A display block for passing the message to our template file 

e A template file for echoing out our Hello world! message 


e Alayout. xml file dedicated to just this module's display blocks under 
the URL/ hel | oworl d/ 


Using the Module Creator script to get 
Hello World 


We'll now go through an automated method of creating a module with backend 
administration. This will show us how to quickly deploy a base of a fully featured 
module in the future. After doing that, we'll go through this code to understand how 
it all works individually. 


We can find the Modul e Creator available as an extension 
=v on Magento Connect at the following link: htt p: // www. 
GA magentocommerce.com/extension/1108/ modulecreator. 
Credit for the Module Creator script goes to Daniel Nitz, with 
the example templates being created by Alistek. 
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This script allows us to put together a solid base of required files for our modules, 
without having to manually create each file. It saves some time when creating all the 
individual files and all developers should know about this when getting into regular 
module development for Magento. While it's not a substitute for knowing how to 
put together the modules ourselves, it does help when we need to get a module up 
and running quickly (most useful when we need a base with which to expand into 
what we want to build). 


Installing the Module Creator 


The following sequence is to be followed when installing the Module Creator: 


1. We'll get started by going to the extension page on Magento Connect for 
the Module Creator and grabbing the key for this extension. 


2. Next, we'll insert the extension key from the Module Creator Magento 
Connect extension page at: http://www. magentocommerce. com/ 
extension/1108/modulecreator. 


p 


We'll open / downl oader/ into the input box (at the top of the page) and 
copy and paste the extension key into the input box at the top of the page. 


E Search for modules via Magento Connect 








EJ Paste extension key to install: ‘magento -community/Netz98_ModuleCreator | instat | 











4. We'll proceed by clicking Install to install the module into our 
Magento installation. 


A success message (similar to the one shown in the previous screenshot) is displayed. 
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Creating our first module with the Module 


Creator 


We'll start by loading the / modul eCreator/ in our Magento installation's URL in 
the browser. A default first screen is displayed, now that it's installed: 





Log In 


Please re-enter your Magento Adminstration 
Credentials. 

Only administrators with full permissions will be 
able to log in. 





Usemame: 





Password: 

















When we log in with the Magento administrative credentials, we'll find ourselves 
inside the script of the Module Creator, and the functionality screen will unveil 
itself. It will look similar to the following screenshot: 








Magento Module Creator 


Skeleton Template: Blank News Module "$ 


could build your o 





Namespace: 
6.9. your Company Name 





Module: 


New 





Magento Root Directory: ‘/home/example/install/public/ 





Design: F 





Design: 








create uninstall 


To create a new module, insert Namespace and a Module 
name (e.g. Blog, Forum, etc.) as well as your design above. 
If you want it to be installed right away into your Magento, 
enter your Magento install path. 
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All options are available to us in this initial screen, along with installed skeleton 
module templates (with scripts). These can be loaded individually if we want to 
install more later for rapid deployment. We can also develop a Skeleton Template 
on our own, in future. 


We'll be using a Blank News Module, which is the default available module with 
the Module Creator extension. 


It's important to note that the Magento Root Directory field is relevant to the 
current location of the Module Creator directory. If the Module Creator is located 
athttp://example.com/modul eCreator/ and our Magento installation is located 
athttp://exampl e. com/ , then we can simply insert. ./ as the value for this field 
and it will work. In most cases, the correct value of this field should insert itself 
automatically into the input field, so that we do not have to figure out the correct 
path ourselves. 


As we'll be using the default theme for easier display throughout this book, it's 
advisable to leave the two design fields blank. If we use this Module Creator in 
our installation with our own theme, these fields will need to be filled in. 


For this chapter we'll be using the following: 








Field Value 
Namespace Book 
Module Helloworld 
Magento Root Directory / 

Design 

Design 





Next we'll click on Create, and the following message gets displayed: 
New Module successfully created! 
Go to the folder where this file is located. You'll find a new folder called new. 


Within are all required files for your new module. This folder has the same structure 
as your Magento installation. Just make sure you replace thei nterface and theme 
folder with your current design path. If you want to add custom DB-fields go to / 
new/l|ocal/Book/Helloworl d/sql/module_ setup/ mysql 4-install-0.1.0. php 
and make your changes for line 12 to 14. 


Copy/new/ Book_Helloworld. xml to /app/etc/ modul es/ .If youchosea 
Magento install directory, all files can be found in their according directory. 
Implement your module functionality and you're done! 
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The contents of our new module 


The module will create a solid amount of files for us to start with. The Module 
Creator would have installed the following files: 


e app/etc/modules/Book_ Helloworld.xm 

e app/code/local/Book/ Hell oworld/Block/Helloworld. php 

e app/code/local/Book/Helloworld/controllers/IndexController. php 
e app/code/local/Book/Helloworld/etc/config.xm 

e app/code/local/Book/Helloworld/Model/Helloworld. php 

e app/code/local/Book/ Hell oworld/Model/ Mysql 4/Helloworld. php 

e app/code/local/Book/ Hell oworld/ Model / Mysql! 4/ Hell oworl d/ 


Collection. php 
e app/code/local/Book/Helloworld/Model/Status. php 


e app/code/local/Book/Helloworld/sgl/helloworld setup/ mysql 4- 
install-0.1.0.php 


e app/design/frontend/default/default/layout/helloworld.xm 


e app/design/frontend/default/default/templ ate/ hell oworl d/ 
helloworld. pht ml 








e app/code/local/Book/Helloworld/Block/Adminht ml /Helloworld. php 

e app/code/local/Book/ Hell oworld/Block/Admi nht ml/ Hell oworl d/Edit 
php 

e app/code/!ocal/Book/ Hell oworld/Block/Admi nht ml/ Hell oworl d/Grid. 
php 

e app/code/local/Book/ Hell oworl d/Block/Admi nht ml/ Hell oworl d/Edit/ 
Form. php 

e app/code/local/Book/ Hell oworld/Block/Admi nht ml / Hell oworl d/Edit/ 
Tabs. php 

e app/code/local/Book/ Hell oworld/Block/Admi nht ml/ Hell oworl d/Edit/ 


Tab/ Form. php 

e app/code/local/Book/Helloworld/controllers/Admi nht ml / 
Helloworl dController. php 

e app/code/local/Book/Helloworld/ Hel per/ Data. php 

e app/design/adminhtml/default/default/layout/helloworld. xml 


If we didn't choose a Magento Root Directory, we'll need to manually copy the files 
to their chosen locations, rather than have the installer doing it. The Module Creator 
will place all the files within a directory called / new/ within our / modul eCreator/ 
folder. If this is the case, then we'll need to copy the files into their duplicate root 
folders. For example / modul eCreator/new/ app/etc/ modul es/ would go into / 
app/etc/modules/ and we would need to match this structure throughout. 








[132] 


Chapter 7 





Hello World 


Now that we have our module's core files ready, we want to get a simple Hello 
World message displayed. We'll start by opening: app/ desi gn/frontend/ def aul t/ 
default/template/helloworld/helloworld.phtml. 


At the top of the file, we'll find the following: 

<h4><?php echo $this-> _('Module List') ?></h4> 
We'll change that to Hel |o World: 

<h4><?php echo $this-> (‘Hello World') ?></h4> 


We'll save he! | oworld. pht ml and then load / helloworld on our Magento 
installation's installation URL; the following screenshot is displayed: 


S 
M Magento 
Default welcome msg! 


Demo Store 


OLAP OTITA English $ 


Furniture Electronics Apparel 





x Hello World a MY 
Did you know? — 
Our customer service is sts avi - items in your 
available 24/7 
ee onl =| COMPARE PRODUCTS 


Hold on, help is 
on the way 





You have no items to compare. 


BACK TO SCHOOL 


Keep your eyes open 


for our special Back 
© POPULAR TAGS to School items 


Camera Hohoro SEXY Test and save BIG! 
apale bones COO! cool 
notebook phone red tignt young 














COMMUNITY POLL 


What is your favorite Magento 
feature? 





Layered Navigation 


NEWSLETTER 9 Price Rules 


Sign up for our newsletter: Category Management 





Compare Products 








Now we have our Hello World using the Module Creator! 
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Expanding our module further into a 
database-driven, administrated brands 
module 


We'll now take the development of our module further and create a database-driven 
list of brands for a section of the site. This part of the chapter will teach us how 
convert the pieces that we built at the start, into a fully functional module 

within Magento. 





Our module will do the following: 


e List a series of brands 


e Turn those brands into links, which clicked, show the brand's name and an 
outline of the location and history of that brand 


e Store this data in a database table within the Magento database 


e Make it content manageable in the administration of Magento, including 
adding, editing, and deleting items 


Recreating the base 


For the sake of making it easier to progress through this chapter, we'll recreate what 
we did at the start. This will help when we do not want to read everything that we've 
previously gone through so far. Explanations of these code blocks are at the start of 
the chapter. 


After this, we will add to the base that we've already created earlier in the chapter 
and introduce a database setup and backend administration into the module. 


The directory structure 


The directory structure for the module's core files is as follows: 


e /app/code/local/Book/ Brands/ 
° Block/ 
> ~controllers/ 
° etc 


° Model/ 
° Mysql4/ 
° Brands/ 
° sql! 


° brands_setup/ 
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For the module's design template files, we have: 


e /app/design/frontend/default/default/ 
° template/ 
° brands/ 


Enabling the module in the backend 


The file/app/etc/modules/Book_Brands. xml will be created for our module 
and it will contain the following: 


<?xml version="1. 0"?> 
<config> 
<modul es> 
<Book Brands> 
<active>true</active> 
<codePool >l ocal </codePool > 
</Book_ Brands > 
</ modul es > 
</ confi g> 


Our controller 


We'll create the file /app/code/local/Book/Brands/controllers/ 
IndexController. php and fill it with the following code: 


<?php 
class Book Brands _IndexController extends Mage Core Controller _Front_ 
Action 
{ 
public function indexActi on( 
{ 


$this->loadLayout() 
$this->renderLayout() 
} 
} 
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Configuring the module 


We'll create the file /app/code/local/Book/Brands/etc/config.xml and fill it 
with the following code: 


<?xml version="1.0"?> 
<config> 
<modul es > 
<Book Brands > 
<version>0.1.0</version> 
</ Book _Brands> 
</ modul es> 
<frontend> 
<routers> 
<brands > 
<use>standard</use> 
<args> 
<module>Book_ Brands </ modul e> 
<frontName>brands</front Name> 
</args> 
</brands> 
</routers> 
<l ayout > 
<updates> 
<brands> 
<file>brands. xml </file> 
</brands> 
</updates> 
</|l ayout> 
</frontend> 
<gl obal > 
<bl ocks> 
<brands> 
<class>Book Brands _Block</class> 
</ brands> 
</ bl ocks> 
<hel pers> 
<brands> 
<class>Book Brands Helper</class> 
</brands> 
</hel pers> 
</ global > 
</ confi g> 
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The Helper model 


We'll create the file / app/code/!ocal/Book/Brands/ Hel per/ Data. php and place 
the following code within it: 


<?php 


class Book Brands Helper Data extends Mage Core Helper Abstract 
{ 
} 


The module's default model 


For the default model, we'll create the file / app/code/|ocal/Book/ Brands/ Model | 
Brands. php and place the following code within it: 


<?php 


class Book Brands Model Brands extends Mage Core Model Abstract 


{ 


public function _construct() 
{ 
parent:: construct(); 
$this->_init('brands/brands'); 
} 
} 


The module's frontend display base 
Here we'll put together the template blocks that form the display of this module. 


Display block class 


We'll create / app/code/!ocal/Book/ Brands/ Block/ Brands. php file and place 
within it the following code: 


<?php 
class Book Brands Block Brands extends Mage Core Block _Templ ate 


{ 


public function _prepareLayout() 


{ 
return parent:: prepareLayout(); 
} 
public function getBrands() 
{ 
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return 'Brands will go here'; 
} 
} 


The layout .xml file 


We'll create the file/app/design/frontend/default/default/layout/ brands. 
xml and place the following code within it: 


<?xml version="1.0"?> 
<layout version="0.1.0"> 
<brands_index_index> 
<reference name="content"> 
<block type="brands/brands" name="brands" /> 
</reference> 
</brands_index_index> 
</| ayout > 


The design template file 
We'll create the file/app/design/frontend/default/default/templ ate/ Brands/ 
brands. phtml and place the following in it: 


<h2><?php echo $this->getBrands(); ?></h2> 


Extending the base towards introducing a 
database 


Now that we have the base for our brands list, we need to advance it to introduce 
our database integration. 


The configuration .xml file 

We'll be editing the existing config. xml file to include our database configuration. 
For shortening the code, existing template tags from the previous conf i g. xml 

file have been shortened witha... separator in between them to show that they 
are unedited. 


We'll edit our config. xml file to include the following outside of the... separators: 
<?xml version="1,0"?> 
<config> 
<modul es > 
</ modul es > 


<frontend> 
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</frontend> 
<gl obal > 
<model s> 
<brands> 
<class>Book Brands Model </class> 
<resourceModel >brands_ mysql 4</resourceModel > 
</ brands > 
<brands_ mysql 4> 
<class>Book_ Brands Model Mysql 4</class> 
<entities> 
<brands> 
<table>brands</table> 
</ brands > 
</entities> 
</ brands mysql 4> 
</ models > 
<resources> 
<brands_ setup> 
<setup> 
<modul e>Book Brands</ modul e> 
</setup> 
<connection> 
<use>core setup</use> 
</ connection> 
</brands_setup> 
<brands_write> 
<connection> 
<use>core write</use> 
</ connecti on> 
</brands_write> 
<brands_read> 
<connection> 
<use>core read</use> 
</ connection> 
</ brands _read> 
</resources> 
<blocks> 
</ bl ocks > 
<hel pers> 
</ hel pers> 
</ gl obal > 
</ confi g> 
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We'll go into the detail of how config. xml and what they do. Our <model s > tag 
introduces database specific models that require my$QL4 in order to operate. This is 
why we're appending _ mysql 4 and _ Mysql 4 onto the end of the class names and a 
<resourceModel > tag in the code: 


<model s> 
<brands> 
<class>Book Brands Model </class> 
<resourceModel >brands_ mysql 4</resourceModel > 
</brands> 
<brands_ mysql 4> 
<class>Book Brands Model Mysql 4</class> 
<entities> 
<brands> 
<tabl e>brands</table> 
</brands> 
</entities> 
</brands_ mysql 4> 
</ model s > 


The second block of code introduced into conf i g. xml covers database resources and 
what the module will use. This defines that the module has a setup file included that 
needs to be executed and checked on update. We'll leverage Magento's core setup 
and write and read database connection settings in order to access the database. 


<resources> 
<brands_ setup> 
<setup> 
<module>Book_ Brands </ modul e> 
</setup> 
<connection> 
<use>core setup</use> 
</connection> 
</brands_setup> 
<brands_write> 
<connection> 
<use>core_write</use> 
</connection> 
</brands_write> 
<brands_read> 
<connection> 
<use>core read</use> 
</connection> 
</brands_read> 
</resources> 
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The mySQL4 data models 


We'll create the directory and file/ app/code/!ocal/Book/Brands/ Model / Mysql 4/ 
Brands. php and place the following code within it: 


<?php 
class Book BrandsModel Mysql4 Brands extends Mage Core Model Mysql 4_ 
Abstract 
{ 

public function _construct() 

{ 

$this->_init('brands/brands', ‘brands_id') 

} 

} 


Here we'll expand the core my$QL4 database class within Magento. The second value 
in the function $t hi s- >_i nit() should match the Primary Key of our module's 
database table. 


We'll create the directory and file/ app/code/!ocal/Book/Brands/ Model / Mysql 4/ 
Brands/ Collection. php and place within it the following code: 


<?php 


class Book BrandsModel Mysql4 Brands Collection extends Mage Core_ 
Model Mysql 4 Collection_Abstract 


{ 
public function _construct() 
{ 
$this->_init('brands/brands'); 
} 
} 


Just like the previous class, we'll expand Magento's core mySQL classes here, this time 
the mySQL Collection class that Magento uses to collect data from the database. 
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Database setup and installation of the file 


In order for our module to store data in the Magento database, we'll need to set up 
the database in which all the data will be kept, stored, and managed by our backend 
within Magento. 


We'll create the following directory and file/ app/code/|ocal/Book/ Brands/sql/ 
brands_setup/ mysql 4-install-0.1.0. php and place within it the following code: 


<?php 


$installer = $this; 
$installer->startSetup(); 


$installer->run(" 


DROP TABLE IF EXISTS {$this->getTable('brands')}; 
CREATE TABLE {$this->getTable('brands')} ( 
“brands id’ int(11) unsigned NOT NULL auto_increment, 
“brand name’ varchar(255) NOT NULL default '', 
“brand_description text NOT NULL default '', 
“brand location’ varchar(255) NOT NULL default '', 
‘status’ smallint(6) NOT NULL default '0', 
“created time datetime NULL, 
“update time’ datetime NULL, 
PRIMARY KEY (‘brands_id° 
) ENGI NE=InnoDB DEFAULT CHARSET=ut f 8; 
"); 
$installer->endSetup(); 








Let's run through the code that we've just put together here. We start by assigning 
the variable $i nst all er the current Magento parent class. Then we move onto 
initializing the installation and calling the child function st artSetup() to indicate 
that the setup of the module is being started by the system: 


$installer = $this; 
ginstaller->startSetup(); 


We then run the SQL contained within ther un() function through the system. We'll 
notice the inclusion of {$t hi s- >getTabl e('brands')} inthe SQL, which allows 
us to insert the name of a module table (including any prefix that the Magento 
installation may have). Any SQL query which is needed for the module later can be 
included here. 


$installer->run(" 


"yi 
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The file is then finished off with the endSet up() function to complete the install run 
for the module: 


$installer->endSetup(); 


Extending the module to include an 
administration 


Now that we have our base and have extended it to include our database integration, 
we'll take this a step further by including an administration. This is so that we can 
add, edit, delete, and manage our module's information in the backend of Magento 
prior to its display. 


AdminhtmIl directories 


Let's start by adding a couple of directories into our base in which to place all the 
files required to add in an administrative backend. 


These are contained in/app/code/|ocal/Book/Brands/: 


Bl ock/ 
Admi nht ml / 
<Modul e>/ 
Edit/ 
Tab/ 
controllers/ 
Admi nht ml / 


Administrative display blocks 


Magento comes with classes and models for generating the administrative backend 
for modules. This means that we can input the core information for the screens, and 
the actual display of the data fields, grids, information, and buttons are output using 
the currently selected admi nht ml template in the system. 


This automates the processes of paging, exporting data to CSV/ XML, filtering 
data, and searching, thereby saving a lot of work in the development of modules. It 
also provides a consistent user experience for the users of Magento. The all-round 
consistency between the modules that users install and use for their Magento 
installations is a phenomenal benefit provided by this automation. 
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There are several parts to putting together the administration for this module, which 
we're going to go over: 
e acore model, defining the administration to the system 
e anadd/edit model, allowing records to be added or edited as needed 
e a setup of the module's grid display, for the administrative home page 
e a class to declare the edit/add record form 
e aclass to set the tabs positioned to the left of the edit/add record form when 
it is being used 
e aclass to declare fields used in the add/edit record form that appears 
e a controller to bring it all together and process accessed URLs for the module 
in the backend 
e the final editing of the config. xml to set up the administrative backend and 
activate it for our module 


While this may seem like a lot of work to get a backend for a module in Magento, 

it's not as much as would be required for other e-commerce systems (which require 
us to template every screen and action, as well as creating the models/controllers for 
our module). 


This is also designed to show us everything that can be clubbed together in terms 

of an administrative backend for our module in Magento. So, we may end up using 
significantly less for simpler modules that we develop with administrative backends 
in Magento. 


Defining the core administrative backend to the 
system 


To start with, we'll need a model which ensures that the administrative backend is 
held together and appears in the first place. It also defines our sub-menu item and 
the labels for the two core buttons on the administrative screen: 


e Brand manager (our sub-menu item) 


e Add Brand (our Add New Record button) 


We'll create the file / app/code/!ocal/Book/Brands/Block/Adminht ml / Brands. 
php and place the following code inside it: 


<?php 
class Book BrandsBlock_ Adminhtml Brands extends Mage Adminht ml Block_ 


Widget Grid Container 
{ 
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public function __construct() 


{ 

$this->_ controller = 'adminhtml_brands'; 

$this- > blockGroup = 'brands'; 

$this-> headerText = Mage::helper('brands')-> (‘Item Manager'); 
$this->_addButtonLabel = Mage::helper('brands')->__('Add Brand'); 
parent:: _construct(); 

} 


} 


Let's break up the key lines of this file to make sure everything is understood as we 
move forward. 


We'll start by extending the Mage_Adminht ml _Block_Widget_Grid_Container 

class which is Magento's Gri d class for displaying grids of information across the 
backend. We'll also notice that this is used for managing products, orders, customers, 
newsletter subscribers, and every other type of information that is displayed in a 
grid in the backend. 


class Book Brands Block _Adminhtml Brands extends Mage Admi nhtml_Bl ock_ 
Widget Grid Container 


Defining our controller and bl ockGr oup to Magento's Grid Container class lets 
Magento know what controller to look for to process this backend's URLs when 
accessed. It also declares which folder to look into for the models and the container 
that we'll be creating to put together in this administrative backend. This is common 
throughout the code for the administrative setup files. 


$this->_controller = 'adminhtml_brands'; 
$this->_blockGroup = 'brands'; 


We'll finish off by defining our header Text which appears at the top of the index 
page for the module's administrative backend and the text used for the Add Record 
button label. This is the common declaration and setting of key labels in the 
administrative backend and will be used throughout other templates and files in 
this chapter. 


$this-> headerText = Mage::helper('brands')-> __('Brands Manager'); 
$this->_addButtonLabel = Mage::helper('brands')->__('Add Brand'); 
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Defining the add/edit screens to the system 
The following model defines the add/edit screens to the system and sets them up 
for us. 


We'll start by creating the file / app/code/|ocal/Book/ Brands/Block/Admi nht ml / 
Brands/ Edit. php and place the following code inside it: 
<?php 


class Book Brands Block_Adminhtml Brands Edit extends Mage Adminht ml _ 
Block Widget _Form Container 





{ 

public function __construct() 

{ 

parent:: _construct(); 

$this->_objectld = ‘id'; 

$this->_blockGroup = ‘brands’; 

$this->_ controller = ‘adminhtml_brands' ; 

$this->_updateButton('save', ‘label', Mage::helper('brands')->__ 
('Save Brand')); 

$this->_updateButton('delete', ‘label', Mage::helper('brands')->__ 
('Delete Brand' ) 

} 


public function getHeaderText() 
{ 
if( Mage::registry('brands data') && Mage::registry('brands_ 
data')->getid() { 
return Mage::helper('brands')-> ("Edit Brand '%s'", $this->htm 
Escape(Mage::registry(' brands data')->getTitle())); 
} else { 
return Mage::helper('brands')->__('Add Brand') 
} 
} 





} 


Key lines in this code 


The line where we defined the obj ect! d to the system, represents the URL key used 
when the system outputs the / edi t/id/5/ URL. When we change the value from i d 
to brand, we'll have the output of / edit/brand/5/. 


$this->_objectld = 'id'; 
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The get Header Text() function is key in this model, as it provides a way of 
switching between showing an Edit Brand label and an Add Brand label depending 
which screen the user is currently accessing. This is important to understand if we 
want to change this behavior in any way for our own module. 

public function getHeaderText() 


{ 


If the _0bj ect! d set earlier appears in the URL, then we'll be on an Edit Brand page: 


if( Mage::registry('brands data') && Mage::registry('brands_ 
data')->getld() ) { 
return Mage::helper('brands')-> ("Edit Brand '%s'", $this->ht ml 
Escape(Mage::registry(' brands data')->getTitle())); 


If not, the user will be adding a brand, so the Add Brand label is displayed: 


} else { 
return Mage::helper('brands')-> __('Add Brand'); 
} 
} 


The module's grid display declaration 


For this class, we'll define the data grid that is displayed when the user clicks on the 
Manage Brands sub-menu item, under our module's administrative backend menu 
item. Although there's a lot of code to look at, we'll go through it later. 


We'll create the file / app/code/local/Book/Brands/ Bl ock/ Admi nht ml / Brands/ 
Grid. php and place the following code inside it: 
<?php 


class Book_Brands_Block_Adminhtmi Brands_Grid extends Mage Adminht ml _ 
Block_Widget_Grid 


{ 

public function __construct() 

{ 
parent:: _construct(); 
$this->setild('brandsGrid'); 
$this->setDefaultSort('brands_id'); 
$this->setDefaultDir('ASC'); 
$this->setSaveParametersinSession(true); 

} 

protected function _prepareCollection() 

{ 


$collection = Mage::getModel('brands/brands')->getCollection(); 
$this->setCollection($collection); 
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return parent:: prepareCollection(); 


} 

protected function _prepareCol umns() 

{ 

$this->addColumn('brands_id', array( 

' header ' => Mage::helper('brands')->__('1D'), 
'align' =>'right', 
‘wi dt h' => '50px', 
‘index! => 'brands_id', 


iR 
$this->addColumn('title', array( 





' header ' => Mage::helper('brands')->__('Title'), 
'align' =>'left', 
'index' => 'title', 


jJ; 
$this->addColumn('status', array( 


' header ' => Mage::helper('brands')->__('Status'), 
'align' => 'left', 

‘wi dt h' => '80px', 

‘index’ => 'status', 

‘type’ => 'options', 

‘options’ => array( 


1 => 'Enabled', 
2 => 'Disabled', 
Jy 
DE 


$this->addColumn('action', 


array( 
' header ' => Mage::helper('brands')->__('Action'), 
"wi dt h' => '100', 
‘type! => ‘action’, 
‘getter’ => 'getld', 
"actions! => array( 
array ( 
‘caption’ => Mage:: helper 
('brands')->__('Edit'), 
'url' => array('base'=> '*/*/edit'), 
‘field! => 'jid' 
) 
), 
‘filter’ => false, 
‘sortable’ => false, 
"i ndex' => 'stores', 
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‘is _system => true, 
J); 
return parent:: prepareCol umns(); 


} 
public function getRowUr! ( $row) 
{ 
return $this->getUrl('*/*/edit', array('id' => $row->getld())); 
} 


} 
There are four core parts to this model's code that we'll learn: 


The construct. 


The prepareCollection() function, which gathers data from 
the database ready for display. 


3. Preparing the grid's columns. 


The get RowUr I () function. 


The __construct() 


The__construct() function holds the core settings for the module's grid. It starts 
off by defining the module's grid ID; this is used as an XHTML value applied to the 
grid to give it a unique identifier. This is useful if we want to do anything with the 
display by editing the Magento administrative stylesheet. 


$this->setld('brandsGrid'); 


We'll then move on to defining the default sorting key for the table. In this case, we'll 
sort by the database table column br and_ name. We'll set the direction of the order to 
DESC, to make sure that the table records are always in alphabetical order by default. 


$this->setDefaultSort('brand_name'); 
$this->setDefaultDir('ASC'); 


The last variable that is set in the__construct() function defines whether or not 
the user's custom filters and parameters applied to this grid should be saved in 
their session, once they've changed the defaults. This ensures that they can filter by 
another column, go to another page in the backend, and return with their filter and 
ordering intact. If set to f al se, the module's grid page will always retain the default 
settings set in the previous three settings in this function. 


$this->setSaveParametersInSessi on(true); 
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Preparing the columns 


Inthe__prepareCol umns() function, we'll define the columns for display in the 
grid. We'll define several properties for each field, including the label, which field 
this label should be displaying, its wi dth, alignment, field t ype, and (if an option 
field) its options. 


The status field is the best example of this, as it does everything at once: 


$this->addColumn('status', array( 


' header ' => Mage::helper('brands')->__('Status'), 
'align' => 'left', 

'wi dt h' => 'B80px', 

"i ndex' => 'status', 

‘type’ => 'options', 

‘options’ => array( 


1 => 'Active', 
0 => ‘Inactive’, 
), 
)); 


The getRowUrl() function 

This function is used to set the URL for any row in the grid, when a user clicks when 
hovering over a row. The */*/ edit defines that the module's namespace and name 
will appear before the / edi t/ which will begin the URL. It will be then ended with 
the $r ow- >getI d variable, to make sure that it forms a good / edi t/id/ 1 URL to be 
passed to the system for ensuring that the user is editing the record with the ID 1. 


public function get RowUr! ($row) 


{ 
return $this->getUrl('*/*/edit', array('id' => $row->getld())); 
} 


Preparing the form 


This model defines the preparation of our form for loading. It declares the various 
values of the form (i d, action, and met hod) to the system following the conventions 
previously outlined in other models. 


We'll create the file / app/code/|ocal/Book/Brands/ Bl ock/ Admi nht ml / Brands/ 
Edit/ Form. php and place the following code inside it: 
<?php 


class Book Brands Block_Adminhtml _Brands_Edit_Form extends Mage_ 
Adminht ml Block Widget_Form 
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protected function _prepareForm) 

{ 

$form = new Varien_Data_Form(array( 
'id' => 'edit_form', 
‘action’ => $this->getUrl('*/*/save', array('id' => $this- 

>getRequest()->getParam('id'))), 

'method' => 'post', 
) 

E 

$form- >setUseContainer(true); 

$this->setForm($form); 

return parent:: prepareForm(); 


} 


Defining the add/edit form tabs 

This module is where the tabs positioned on the left of the form containing different 
data are set up. In this case we'll only set up one tab, as we don't have enough fields 
for them to be divided into multiple tabs. 


We'll create the file / app/code/local/Book/Brands/ Bl ock/ Admi nht ml / Brands/ 
Edit/ Tabs. php and place the following code inside it: 


<?php 


class Book Brands Block _Adminhtml _Brands_Edit_Tabs extends Mage_ 
Adminht ml Block _Widget_Tabs 
{ 


public function 


{ 


__construct() 

parent:: construct(); 

$this->setild('brands_tabs'); 
$this->setDestElementid('edit_form'); 
$this->setTitle(Mage::helper('brands')->__('Brand Information')); 


} 


protected function _beforeToHt ml () 
{ 
$this->addTab('form section’, array( 
‘lLabel' => Mage: :helper('brands')-> (‘Brand Information'), 
‘title! => Mage: :helper('brands')->__('Brand Information'), 
‘content’ => $this->getLayout()->createBlock(' brands/ 
adminhtml _brands_edit_tab_form')->toHtml(), 


H 
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return parent:: beforeToHtml (); 
} 
} 


There are two key things going on here in this model. Firstly, in the __construct() 
function we'll be setting the edi t_f or mas the default form and Brand Information 
as the default title to show when a add/edit form is shown: 


$this->setild('brands_tabs'); 
$this->setDestElementid('edit_form'); 
$this->setTitle(Mage::helper('brands')->__('Brand Information')); 


Secondly, in the bef oreToHt ml () function the actual adding of the tab to the form 
takes place: 


$this->addTab('form_section', array( 


‘lLabel' => Mage::helper('brands')->__('Brand Information'), 
‘title! => Mage::helper('brands')->__('Brand Information'), 
‘content’ => $this->getLayout()->createBlock(' brands/ 


adminhtml _brands_edit_tab_form')->toHtml(), 
Ly 


Here the label and title are both defined as Brand Information and we'll make sure 
to block admi nht ml_brands_edit_tab_form, asit's used for the tab's form. This 
form is declared in the following class. 


Configuring and preparing the form for display 


Following the tab being declared to show our form block, we'll need to create it. In 
this model well' creating the form block to be displayed when the form tab we've just 
declared in the previous file is clicked. We're setting up the fieldsets and fields that 
are to be used for the form block that appears. 


We'll create the file / app/code/local/Book/Brands/ Bl ock/ Admi nht ml / Brands/ 
Edit/Tab/ Form. php and place the following code inside it: 


<?php 
class Book Brands Block _Adminhtml _Brands_Edit_Tab_ Form extends Mage_ 
Adminht ml Block Widget_Form 
{ 
protected function _prepareFor m( 
{ 
$form = new Varien Data_ Form) 
$this->setForm( $form) 
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$fieldset = $form >addFieldset('brands form, array('legend' =>Mage 
:ihelper('brands')->__('Brand information'))); 


$fieldset->addField('brand name', 'text', array( 
‘label’ => Mage::helper('brands')-> _('Brand Name'), 
'class' => 'required-entry', 
'required' => true, 
‘name! => 'brand_name', 
DE 
$fieldset->addField('status', 'select', array/( 
‘label' => Mage::helper('brands')-> _('Status'), 
' na me' => 'status', 
‘values! => array( 
array( 
'value' => 1, 
'label' => Mage::helper('brands')->__('Active'), 
Ie 
array( 
'value' => 0, 
‘lLabel' => Mage::helper('brands')-> _('Inactive'), 
Mis 
P 
)); 
$fieldset->addField('brand_location', 'text', array( 
‘label’ => Mage: :helper('brands')-> _(‘Location'), 
'class' => 'required-entry', 
‘required’ => true, 
"name! => 'brand_location', 


$fieldset->addField('brand description’, ‘editor', array( 


' name' => 'brand_description', 

‘lLabel' => Mage: :helper('brands')->__('Description'), 
‘title! => Mage::helper('brands')-> __('Description'), 
‘style’ => ‘width: 98%; height: 400px;', 

' wysi wyg' => false, 

'required' => true, 


yy; 


if ( Mage::getSingleton('adminhtml/session')->getBrandsData() ) 
{ 


$form->setValues(Mage:: getSingleton('adminhtml/session')- 
>getBrandsData()); 


Mage::getSingleton('adminhtml/session')->setBrandsData(null); 
} elseif ( Mage::registry('brands data') ) { 
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$form->setValues(Mage::registry('brands data')->getData()); 
} 
return parent:: prepareForm); 
} 
} 


Three key things happen here. Firstly, we have the fi el dset that is added at 
the start: 


$fieldset = $form->addFieldset('brands form, 
array('legend'=>Mage::helper('brands')->__('Brand Information'))); 


Without this, we can't place the fields anywhere. They need the defined $f i el ds et 
variable in order to add themselves to the form. 


Secondly, the fields are added, in a way remarkably similar to the way they were 
added to the grid for display previously. We have the same options and a few 
additional options such as class, which defines the class of the form field and 
whether or not the field is required upon being input. 


Lastly, we have some cal | back functions to the current session in progress to see if 
they've already tried to fill in this form and failed, therefore needing to place their 
information back in the form rather than the default: 


if ( Mage::getSingleton('adminhtml/session')->getBrandsData() ) 

{ 
$form->setValues(Mage::getSingleton('adminhtml/session')- 
>getBrandsData()); 
Mage::getSingleton('adminhtml/session')->setBrandsData(null); 

} elseif ( Mage::registry('brands data') ) { 
$form->setValues(Mage::registry('brands data')->getData()); 


} 








This function is an extremely useful function to have, in terms of usability and 
consistency of user experience throughout the Magento administration. 


Setting up our brand status array 


A standard across Magento modules and other manageable information in the 
backend is to have statuses assigned to data. For this we'll need to create the file / 
app/code/local/Book/ Brands/ Model/ Status. php and place the following code 
inside it: 

<?php 

class Book_Brands_Model_ Status extends Varien_Object 


{ 
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const STATUS ENABLED = 1; 
const STATUS DISABLED = 2; 
static public function getOptionArray() 
{ 
return array( 
self:: STATUS ENABLED => Mage::helper('brands')-> __ 
('Enabled'), 
self:: STATUS DISABLED => Mage: :helper('brands')->__ 
('Disabled') 


); 


} 
Let's break this down briefly to go over what we've just done. 


To start with, we have two constants being declared to define the stored database 
variables with which Magento will refer to these statuses internally: 


const STATUS ENABLED = 1; 
const STATUS DISABLED = 2; 


After this comes our get Opti onArray() function which defines our array of status 
options that we will implement for our module and their variables: 


static public function getOptionArray() 


{ 
return array( 
self::STATUS ENABLED => Mage: :helper('brands')->__ 
('Enabled'), 
self:: STATUS DISABLED => Mage::helper('brands')->__ 
('Disabled' ) 
i 
} 


This passes an array of the following to Magento for our status array: 





Value Label 
1 Enabled 
2 Disabled 
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Creating a controller to process access URLs 


This controller file will process all the URLs, as they're accessed in the backend. 
We'll see everything split into functions set up as <n a me > Action. For example, / 
module/index/ willbe set up asi ndexAction() and the rest follow the same 
naming convention. 


The code inside this file controls the core actions for these individual URLs and 
sets the individual pages up for loading. 


We'll create the file /app/code/local/Book/Brands/controllers/Admi nht ml / 
BrandsController. php and place the following code inside it: 


<?php 
class Book Brands _Adminhtml BrandsController extends Mage Admi nht ml _ 
Controller_action 
{ 
protected function _initAction( 
{ 
$this->loadlLayout() 
->_setActiveMenu('brands/items' ) 
->_addBreadcrumb( Mage::helper('adminhtml')->__('Brands Manager') 
Mage::helper('adminhtml')->__('Brands Manager')) 
return $this 


} 


public function indexAction() { 
$this->_initAction(); 
$this->renderLayout(); 


} 
public function editAction() 
{ 
$brandsid = $this->getRequest()->getParam('id'); 


$brandsModel = Mage::getModel('brands/brands')->load($brandsl qd); 


if ($brandsModel->getld() || $brandsId == 0) { 
Mage::register('brands data', $brandsModel ); 


$this->loadLayout(); 
$this->_setActiveMenu(' brands/items' ); 


$this->_addBreadcrumb(Mage::helper('adminhtml')->__(' Brands 


Manager'), Mage::helper('adminhtml')->__(' Brands Manager')); 
$this->_addBreadcrumb(Mage::helper('adminhtml')->__(' Brand 


Description'), Mage::helper('adminhtml')->__(' Brand Description'));: 








$this->getLayout()->getBlock('head')->setCanLoadExt]s(true); 
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$this->_addContent($this->getLayout()->createBlock(' brands/ 
adminhtml brands _edit')) 
->_addLeft($this->getLayout()->createBlock('brands/admi nht ml _ 
brands _edit_tabs')); 


$this->renderLayout(); 
} else { 
Mage::getSingleton('adminhtml/session')->addError(Mage:: hel per(' 
brands')->__('Brand does not exist')); 
$this->_redirect('*/*/'); 


} 
} 
public function newActi on( 
$this->_forward('edit'); 
} 
public function saveActi on( 
{ 


if ( $this->getRequest()->getPost() ) { 
try { 
gpostData = $this->getRequest()->getPost() 
$brandsModel = Mage:: get Model('brands/brands') 


if( $this->getRequest()->getParam('id') <= 0 
$brandsModel->setCreatedTi me( Mage::getSingleton('core/ 
date')->gmt Date()); 


$brands Model 
- >addData($post Data) 
->setUpdateTi me(Mage::getSingleton('core/date' )- 
>gmt Dat e( )) 
->setid($this->getRequest()->getParam('id')) 
->save(); 


Mage::getSingleton('adminhtml/session')->addSuccess(Mage:: help 
er('adminhtml')->__('Brand was successfully saved')) 
Mage::getSingleton('adminhtml/session')->setBrandsData(false); 


$this->_redirect('*/*/' 
return; 
} catch (Exception $e) { 

Mage::getSingleton('adminhtml/session')->addError( $e- 
>getMessage()); 

Mage::getSingleton('adminhtml/session')- 
>set<Module>Data($this->getRequest()->getPost()); 

$this->_redirect('*/*/edit', array('id' => $this- 
>getRequest()->getParam'id'))) 

return; 
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} 
} 
$this->_redirect('*/*/'); 
} 
public function deleteActi on() 
{ 


if( $this->getRequest()->getParam'id') >0) { 
try { 
$brandsModel = Mage::getModel('brands/brands'); 


$brandsModel->setid($this->getRequest()->getParam('id')) 
- >delete(); 


Mage::getSingleton('adminhtml/session')->addSuccess(Mage::help 
er('adminhtml')->__('Brand was successfully deleted')); 
$this->_redirect('*/*/' 
} catch (Exception $e) { 
Mage::getSingleton('adminhtml/session')->addError( $e- 
>getMessage()); 
$this->_redirect('*/*/edit', array('id' => $this- 
>getRequest()->getParam('id'))); 
} 











} 
$this->_redirect('*/*/'); 
} 
} 


Let's break down the code and go through it so that you understand what we've just 
done in this file. 


We start out by declaring our Brands Controll er class that will hold the admin 
together. 


<?php 


class Book Brands _Adminhtml BrandsController extends Mage Admi nht ml _ 
Controller_action 


{ 


Our first function is _i ni tAction() which sets the brands/brands manager as 
active in the menu handler in the backend of Magento as well as setting the 
breadcrumb trail. 


protected function _initAction() 


{ 
$this->loadLayout() 
->_setActiveMenu('brands/items' ) 
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->_addBreadcrumb(Mage::helper('adminhtml')->__('Brands Manager'), 
Mage::helper('adminhtml')->__('Brands Manager')); 
return $this; 


} 


Ouri ndexAction() function calls our _i nit Action() function to start and then 
renders the layout. 


public function indexAction() { 
$this->_initAction(); 
$this->renderLayout(); 


} 


Next we're putting actions to our edit function. 


public function editAction() 


{ 


We grab the get parameter ID and use it to load the brand in our database by 
that ID. 


$brandslid = $this->getRequest()->getParam('id'); 
$brandsModel = Mage::getModel('brands/brands')->load($brandsl qd); 


If there's a brand by that ID we're going to setbrands_data in the Magento 
global registry. 


if ($brandsModel->getld() || $brandsId == 0) { 
Mage::register('brands_ data', $brandsModel ); 


Followed by the initializing of the loading for the page layout and setting of the 
active brand navigation item. We'll then make sure we can load the extra functions in 
the JavaScript library should we need them. 


$this->_initAction(); 
$this->_addBreadcrumb(Mage::helper('adminhtml')->__(' Brand 


Description'), Mage::helper('adminhtml')->__(' Brand Descri ption')); 
$this->getLayout()->getBlock('head')->setCanLoadExt] s(true); 


The following loads our content for the page which will load the edit form and any 
tabs that will appear in the left sided navigation of the edit page. 


$this->_addContent($this->getLayout()->createBlock(' brands/ 
adminhtml brands _edit')) 
->_addLeft($this->getLayout()->createBlock('brands/admi nht ml _ 
brands edit_tabs')); 


$this->renderLayout(); 
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If the brand doesn't exist, show an error box with the contents Brand does not exist 
and redirect to the brands index. 


} else { 
Mage::getSingleton('adminhtml/session')->addError(Mage:: hel per(' 
brands')->__('Brand does not exist')); 
$this->_redirect('*/*/'); 
} 
} 


Our newActi on() will handle a new brand being inserted. It will call the 
edi tAction() function and load the form as a new brand instead of one being edited. 


public function newAction() 
{ 

$this->_forward('edit'); 
} 


The saveAction() function will be called once the edit form is posted. 


public function saveAction() 


{ 


We'll check if posted information exists, and if it goes grab it and the br and 
controller module to interface with brand information going forward. 


if ( $this->getRequest()->getPost() ) { 
try { 
gpostData = $this->getRequest()->getPost(); 
$brandsModel = Mage::getModel('brands/brands'); 


If we have a brand ID we'll set the record created time to attach to our database entry 
for the saved brand once inserted. 


if( $this->getRequest()->getParam'id') <= 0 ) 
$brandsModel->setCreatedTi me(Mage::getSingleton('core/ 
date')->gmt Date()); 


Followed by the inserting of the brand into the database. 


$brands Model 
- >addData($post Data) 
->setUpdateTi me(Mage::getSingleton('core/date' )- 
>gmt Dat e()) 
->setid($this->getRequest()->getParam('id')) 
->save(); 








[160] 


Chapter 7 





We then set a success message, remove the saved brand data in the Magento registry 
and redirect to the brands information index. 


Mage::getSingleton('adminhtml/session')->addSuccess(Mage:: help 
er('adminhtml')-> __('Brand was successfully saved')); 


Mage: : getSingleton('adminhtml/session')->setBrandsData(false); 


$this-> redirect('*/*/'); 
return; 


If we have an error at any point we'll set an error message and forward back to the 
brands index. 


} catch (Exception $e) { 
Mage::getSingleton('adminhtml/session')->addError( $e- 
>getMessage()); 
Mage::getSingleton('adminhtml/session')->setBrandsData($this- 
>getRequest()->getPost()); 
$this->_redirect('*/*/edit', array('id' => $this- 
>getRequest()->getParam'id'))) 
return: 
} 
} 
g$this->_redirect('*/*/'); 
} 


The final function in the file is that of the function that handles deletion of records, 
deleteAction(). 


public function deleteActi on() 


{ 


Once again we confirm an 'i d' parameter is set before we continue. 


if( $this->getRequest()->getParam'id') >0) { 
try { 


We then load the brands model and proceed to call the del et e( ) function to remove 
the brand that matches the current set ID. 


$brandsModel = Mage::getModel('brands/brands'); 


$brandsModel->setid($this->getRequest()->getParam('id')) 
- >delete(); 


We can then set a success message and forward back to the brands index. 


Mage::getSingleton('adminhtml/session')->addSuccess(Mage:: help 
er('adminhtml')-> __('Brand was successfully deleted')); 
$this->_redirect('*/*/'); 
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If an error occurs we set an error message and go back to the brands index. 


} catch (Exception $e) { 
Mage::getSingleton('adminhtml/session')->addError( $e- 
>getMessage()); 
$this->_redirect('*/*/edit', array('id' => $this- 
>getRequest()->getParam'id'))); 
} 
} 
g$this->_redirect('*/*/'); 
} 
} 


Next we'll alter our configuration file, so that our XML reflect the code we've 
just implemented. 


Changing the module's config.xml to reflect the 
administrative backend 


Now that we have all our files together for the complete backend administrative 
display of our module, we'll need to define these blocks and actions in our module's 
config.xml file. As we used the separator to define tags that remain unchanged to 
cut down the amount of repeated code. 


We'llopen/ app/code/!ocal/Book/Brands/etc/config.xml and make the 
following additions: 


<?xml version="1.0"?> 


<config> 
<modul es> 
</ modul es > 


<frontend> 


</frontend> 
<admi n> 
<routers> 
<brands> 
<use>admi n</use> 
<args> 
<module>Book_ Brands </ modul e> 
<frontName>brands</front Name> 
</args> 
</brands> 
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</routers> 
</ admi n> 
<admi nht ml > 
<menu> 
<brands module="brands"> 
<title>Brands</title> 
<sort_order>71</sort_order> 
<children> 
<items module="brands"> 
<title>Manage Brands</title> 
<sort_order>0</sort_order> 
<action>brands/adminht ml _brands</action> 
</ items > 
</ chil dren> 
</ brands > 
</ menu> 
<acl > 
<resources> 
<al | > 
<title>Allow Everything</title> 
</ all> 
<admi n> 
<children> 
<Book Brands > 
<title>Brands Module</title> 
<sort_order>10</sort_order> 
</ Book_Brands> 
</ chil dren> 
</ admi n> 
</resources> 
</ acl > 
<l ayout > 
<updates> 
<brands> 
<file>brands.xml </file> 
</ brands > 
</updates> 
</ layout > 
</ admi nht ml > 
<gl obal > 


</ gl obal > 
</ config> 
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We'll break down the additions to our config. xml file so that they once again make 
sense as we proceed forward. 


The first part defines that we have a controller to handle the URLs in the backend: 


<admi n> 
<routers> 
<brands > 
<use>admi n</use> 
<args> 
<module>Book Brands </ modul e> 
<frontName>brands</ front Name> 
</args> 
</ brands> 
</routers> 
</ admi n> 


We then have a starting <admi nht ml > block tag, which brings in three groups 

of configuration options to the file, the first of which defines our menu to the 
administrative backend. It defines the title of the menu item, the sort order (when 
it should appear in the order of the main menu items), and the sole sub-item in the 
menu (referred to as children). We'll call it Manage Brands: 


<menu> 
<brands module="brands"> 
<title>Brands</title> 
<sort_order>71</sort_order> 
<chil dren> 
<items module="brands"> 
<title>Manage Brands</title> 
<sort_order>0</sort_order> 
<action>brands/admi nhtml _brands</action> 
</i tems > 
</children> 
</ brands > 
</ menu> 


The second of the <admi nht ml > block tag group defines permissions for our module. 
It defines which resources should be made available as options to select in the 
permissions section of setting up a user and what it should allow them access to 

in the administrative backend. Here we've defined an Allow Everything resource 
group which allows complete access to do anything in our module to the user or user 
group given the permission: 


<acl > 
<resources> 
<al | > 


<title>Allow Everything</title> 
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</ all> 
<admi n> 
<children> 
<Book Brands > 
<title>Brands Module</title> 
<sort_order>1l0</sort_order> 
</ Book _Brands> 
</ chil dren> 
</ admi n> 
</resources> 
</ acl > 


The third and last set of tags in the new <admi nht ml > block tag of configuration 
options defines the layout. xml file, which provides the display blocks for processing 
when the URLs are accessed: 


<l ayout > 
<updates> 
<brands> 
<file>brands. xml </file> 
</brands> 
</updates> 
</| ayout > 


This layout. xml file is going to be created next in our process. 


Giving our administrative backend a layout .xml file 


Just like on the front end, we'll need to create a layout. xml file for our admi nht ml 
files defined for Magento. This pulls everything together and ensures that everything 
loads properly. 


We'll create the file/app/design/adminht ml/default/default/layout/ brands. 
xml and place the following inside of it: 


<?xml version="1.0"?> 
<layout version="0.1.0"> 
<brands_adminhtml brands _index> 
<reference name="content"> 
<block type="brands/adminhtml_ brands" name="brands" /> 
</reference> 
</brands_adminhtml brands_index> 
</|l ayout > 
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This will ensure that when we access our module in the backend, it loads as it 
should through the controller that we created for it earlier and along with all 
subsequent files. 


With the addition of this file, we have ourselves a fully active administrative backend 
for our module that connects with the database table that we put together earlier. 


A look at the administrative backend 


Let's take a minute or two to admire what the backend looks like, now that we've put 
it together and everything is in the system. 





Manage Brands 





In the following screenshot, we'll look at the data display grid: 





Brand Manager 
Page 4 of 1 pages | View | 20 $  perpage | Total 1 records found od Ea 
| 1D f Title Status Action 

a 
$ 
1 Example brand 1 Enabled Edit 











The Add Brand form is shown in the following screenshot: 


Add Brand + Back | RZ 


Brand Name * 





Status Inactive 


- 


Location * 


Description * 
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The final stage in this process is making sure all the information from the backend 
administrative component can output on the frontend of the system, when the URL 
is accessed. This is done by editing the display block models and template files that 
we setup earlier in the chapter for both, brands list, and a singular brand view. Here 
we can use the data that we've put together as needed. 


Let's look back at the fields that we set up for our module: 


e brandid 

e brand name 

e brand description 
e brand location 

e status 

e updated time 

e created time 


For our purpose, we'll set up the following: 


1. An index loading function, which lists all (active status) brands in the 
database and when they were last updated. 


2. A singular brand loading function, which lists all information that we have 
on the individual brand being viewed. 


The index controller 


To start off, we need to ensure that we load the data correctly on the core index and 
also while viewing the individual brand's page. Here we'll make sure that the data is 
loaded for it to be used in our template files on the frontend. 


We'll open and edit / app/ code/|ocal/Book/ Brands/controllers/ 
| ndexController. php file and make sure it looks like the following: 


<?php 
class Book Brands _IndexController extends Mage Core Controller _Front_ 
Action 
{ 

public function indexActi on( 


{ 
$brands_id = $this->getRequest()->getParam('id'); 


if($brands_id != null && $brands id !='') { 
$brands = Mage::getModel('brands/brands')->load($brands_id)- 
>getData(); 
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} else { 
$brands = null; 


} 


if($brands == null) { 

gresource = Mage::getSingleton('core/resource'); 
gread= $resource->getConnection('core read'); 
$brandsTable = $resource- >getTabl eName('brands'); 


$select = $read->select() 
- >from $brandsTable,array('brands_id','brand_ 
description','brand_location','status')) 
->where('status', 1) 
->order('created time DESC') ; 


$brands = $read->fetchRow($select); 


} 


Mage::register('brands', $brands); 


$this->loadlLayout(); 
$this->renderLayout(); 
} 
} 


Let's go through these edits to make sure that everything is clear. 


First off, we'll start by assigning $br and the value of $_GET['id'] . We'll use this 
function, as it filters out any cross-site scripting and to eliminate the bad things that 
can happen to the raw variable, when we use it as we please. 


$brands_id = $this->getRequest()->getParam('id'); 


If this value isn't blank (that is, if we're looking at a singular brand's page), then we'll 
call the | 0ad() function from our brands data model. If not, then we set $brands to 
null for the next bulk of the code that follows. 


if($brands_id != null && $brands_id !='') 
$brands = Mage::getModel('brands/brands')->load($brands_id)- 
>getData(); 
} else { 
$brands = null; 
} 


If$brands == null, then this means that we're not looking at an individual brand 
page and are looking at the index, which needs to list them all. 


if($brands == null) { 
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We'll assign the database functions to the variable $r es our ce and make sure that 
we use the core_read database setup and assigning the brands table name to the 
variable $brandsTable. 


gresource = Mage::getSingleton('core/resource'); 
gread= $resource->getConnection('core read'); 
$brandsTable = $resource- >getTabl eName('brands'); 


Now we will build the query needed to obtain all brands from the table where 
status = 1 ordered by the newest created to oldest entries in the table. Status 1 
means Enabled in this case. 


$select = $read->select() 
-> from($brandsTable, array('brands_id','brand description',' brand_ 
location','status')) 
- >where('status', 1) 
->order('created time DESC') ; 


$brands = $read->fetchRow($sel ect); 


} 


To finish off, $br ands, which is now set to either a group of all the brands or a 
singular brand, is now registered as a variable which can be accessed across the 
module further on: 


Mage::register('brands', $brands); 


Displaying the brands data 


To display the data that we've set by editing our index controller, we'll open and 
make edits to the module's template file located at the address / app/ desi gn/ 
frontend/default/default/templates/brands/ brands. phtml. Here's the file 
after the edits are made: 


<?php 
$brands = $this->getBrands(); 
if ( count($brands) > 0 
{ 
foreach ( $brands as $brand 
echo '<h3><a href="'.$this->getUrl('brands?id='.$brand[' brand_ 
id']).'">Name: '.$brand['title'].'</a></h3>' 


echo '<p><strong>Location: '.$brand['location'].'</strong></p>'; 
echo '<p>Desciption: '.$brand['brand_description'].'</p><hr />'; 
endforeach; 
} 
else 
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{ 
print 'We don\'t have any brands here right now. Please try again 
later.'; 


} 
We'll go through this code step by step. 


We start off by assigning the brands (if we're on the index) or brand (if we use 
?i d=<brand_id> on the end of the URL) to the variable $brands. 


$brands = $this->getBrands(); 


We then need to make sure that this is an array. If it isn't, then our data model tells 
us that the result is not found. 


if (count($brands) >0) 
{ 


If we have a result inside our array (or multiple results), then we go through them 
inaforeach loop and echo out simple formatting to display them on the site: 


foreach ( $brands as $brand ) 
echo '<h3><a href="'.$this->getUrl('brands?id='.$brand[' brand_ 


id']).'">Name: '.$brand['title'].'</a></h3>'; 
echo '<p><strong>Location: '.$brand['location'].'</strong></p>'; 
echo '<p>Desciption: '.$brand['brand_description'].'</p><hr />'; 


endforeach; 


However, if we don't have a result inside the array, we'll display a simple message 
to the person visiting the page that we don't have any brands just yet and that they 
need to come back a little bit later. 


} 


else 


{ 
print 'We don\'t have any brands here right now. Please try again 
later.'; 


} 


There we go, we have our module's data displaying on the frontend! If we follow 
all the steps in this chapter, then our brand data display will look as shown in the 
following screenshot: 
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Summary 


In this chapter, we've covered the basics of creating an advanced module for 
Magento. With this knowledge, we will be able to progress onto building more 
advanced modules in Magento. 


We've covered multiple topics on building modules including: 


e Setting up the module 

e Getting our first Hello World output on its own dedicated URL 

e Creating a sample module quickly through the Module Creator script 

e Altering and editing this sample module to create our very own Brands 
Management module 


After reading this chapter, we should try and enhance it by: 


e Adding more fields and information to the brands output 

e Splitting brands into pages — for example, 1, 2, 3, 4, and so on 

e Giving brands their own singular templates and custom URLs 

e Building a form to accept submissions on the brands which people would 
like to see added onto the site or to take requests 

e Allowing users to review brands 

e Providing the brands more information than on the listing, for each 
individual brand page to display 
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Other small modules we could develop, to use the knowledge gained in this chapter 
and put it to practical use by analyzing, include: 

e A Google maps inclusion module — to include a simple Google map 

e A Twitter/Flickr/ del.icio.us feed inclusion script 


e A basic blog/news system 
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Integration of Third-Party 
CMS 


Sometimes, the built-in content management functionality of Magento isn't enough 
for our site, or we need a blog or news section in addition to Magento's e-commerce. 
In some cases, it's the other the way around, and we would like to add Magento's 
e-commerce functionality to our chosen content management system. 


In this chapter we'll go over a few of the content management system integration 
options available, while focusing on WordPress. We will learn the following: 

e Installing the WordPress extension 

e Configuring the WordPress extension 

e Configuring Magento's display of the WordPress extension 


e Changing the look and display of your templates for the WordPress 
integration 


e Which other third party CMS integration packages and extensions 
for ExpressionEngine, Drupal, Typo3, and Joomla! are available 


Notable things about CMS Integration 


We must ensure that we back up both our Magento installation and our CMS 
installation before editing them. Sometimes, the core files are to be edited, and so 
we'll need to keep a backup of the original version of the files before editing them. 
Keeping a copy of the database is also advisable. 


Integration of Third-Party CMS 





It's also advisable to back up the files with changes intact after finishing the 
integration, in case an upgrade of either system knocks the integration out of sync. 


The WYSIWYG editor implementation 


If we simply want to implement a WYSIWYG editor into our Magento install, 
there are two available modules that can be installed to integrate this functionality 
available at the following URLs: 


http://www. magentocommerce.com/extension/586/fontis-wysiwyg-editor. 


http://www. magent ocommerce.com/ extension/1426/bounci ngorange-tinymce- 
wysiwyg. 


Integrating Wordpress 


In this section, we'll learn about integrating Wordpress with Magento. 


(GY) worvpress 


WordPress is an entirely open source, free system available for download 
_ by anyone who can navigate tohttp://wordpress.org/download/. 
Initially built to be a small content management system based around 
> improving typography, WordPress has grown to power hundreds and 
thousands of blogs worldwide and is the biggest self-hosted blogging tool 
available on the web today. 


Here, we'll install a popular available module by the name of Lazzymonks, a 
WordPress integration from Magento Connect for integrating WordPress into 
Magento. It enables the viewing of blog posts and pages within the Magento 
layout, as well as a sidebar block being included in the module for archives, 
categories, and RSS feed links to be shown to the users. 
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Installation 


To install the WordPress integration module, we need to make sure that both 
Magento and WordPress are installed in the same database; otherwise, the module 
will not work. 


Before we start, it must be ensured that our preferred state setting is set to beta, 
as this module is currently marked as, in beta development. This can be found under 
the settings tab whilst within the downloader. 


We must also ensure that our WordPress installation is installed in a folder named 
/wordpress/ in our root Magento installation folder. This is also vital as the 
extension does not look for any other folder and is currently not configurable to look 
for folders not named / wordpress/. 


The module that we'll be installing is located at: http://www. magent ocommerce. 
com/extension/296/lazzymonks-wordpress-integrati on. 





© Get extension key 











Once we find and load the page for the Lazzymonks Wordpress Integration plugin 
we click on the Get extension key button (shown in the previous screenshot) to 
unveil the extension key for the module. We have to make sure to copy the extension 
key from the input area for the next step. 


Next, we load up our Magento Connect downloader located at/ downl oader/ from 
our root installation address or System->Downloader in the Magento administration 
menu. Once we have logged into the downloader, we paste the extension key into the 
text input located under Install New Extensions, as shown in the following screenshot: 





Install New Extensions 


EI Search for modules via Magento Connect, 


EJ Paste extension key to Install: | magento-community/Mage_Blog | install | 
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The install should be relatively quick: 





We openi ndex. php from our Magento installation folder and find the line: 
require_once $mageFil ename; 
Next, we place the following code after the above code: 


define('WP_USE_THEMES', true); 
require('./wordpress/wp-blog-header. php'); 


We must make sure that the second line here points to our WordPress installation, 
otherwise this will break. 


After that, we open / wordpress/wp-settings. php. We will need to find and 
remove the & symbol from the code. This is to make the code compatible with 
Magento. The line numbers are placed for a quick reference, roughly related to the 
latest version of WordPress: 


Line 520: 
$wp_the query =& new WP _Query(); 
Line 535: 
$wp_rewrite =& new WP_Rewrite(); 
Line 524: 
$wp =& new WP(); 
Line 578: 
$wp_locale =& new WP_Locale(); 
Next, we find the following and comment it out (around Li ne 583): 


II Escape with wpdb. 

$_GET = add_ magic _quotes($_GET ); 
$_POST = add_magic_quotes($ POST ); 
$ COOKIE = add_magic_quotes($_ COOKIE); 
$ SERVER = add_magic_quotes($ SERVER); 
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This results in the following: 


II Escape with wpdb. 

1/1 $_GET = add_magic_quotes($_GET ); 
//$_POST = add_magic_quotes($_POST ); 
/1$_COOKIE = add_magic_quotes($_ COOKIE); 
/1$_SERVER = add_magic_quotes($_ SERVER); 


We'll keep them in (rather than removing them), so that it is easier to reverse the 
changes later if we need to (if we're uninstalling). 


Now, we open wordpress/wp-includes/!10n. php and find the following (in 
WordPress 2.7.1, on Line 112): 


function ($text, $domain = 'default') { 
return translate($text, $domain); 
} 


Next, we replace this block of code with the following to allow Magento's translate 
function to operate, where necessary: 


if (!function_exists('__')) { 

function ($text, $domain = 'default') { 
return translate($text, $domain); 

} 

} 


That's all for the code edits needed for installation. After we have done this, we 

will take the magento folder from within / wordpress module _files/Wordpress- 
theme/ and place it within our / wordpress/wp-content/themes/ Wordpress 
themes folder. This will give WordPress a theme called Magent 0, which allows us to 
interface with the Magento installation. 
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Next, we log into our WordPress administration and go to Appearance->Themes, 
where we'll see the Magento theme that is now available: 





a 
O 





4 


(Ee 
an 
Ei 


WordPress Magento 





The Theme required to get magento and 
wordpress working in harmony 











We click the title to pop up the theme preview and activate it. If we navigate 
to/wordpress/ directly, we will receive a blank page. 


We go to Settings->General and change our WordPress URL to our Magento 
installation URL / bl 0g/ . For example, this means that if our Magento installation 
isathttp://localhost/ magento/ , then our WordPress URL would be 


http://localhost/ magento/ bl og. 


We must make sure to save and then head over to Settings->Permalinks. It must be 
ensured that the Permalinks are set to Default and turned off entirely; otherwise, 
this will affect our Magento/WordPress integration. Hopefully better Permalinks 
will be implemented in a future version of this module. 





Common settings 


@ Default 





http: //m. jhuskisson. com/blog/?p=123 
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When we navigate to our newly set WordPress URL, we will see our newly 
integrated WordPress blog within our store, as shown below: 


Search entire store here... Search’ 


Demo Store Default welcome msg! 


M Magento 





Hello world! 2 MY CART 
May 9th, 2009 You have no items in your 
shopping cart. 


Welcome to WordPress. This is your first post. Edit or delete it, then start blogging! 


Posted in Uncategorized 1 Comment » 
=| COMPARE PRODUCTS 


You have no items to compare. 


BACK TO SCHOOL 


Keep your eyes open 


for our special Back 
to School items 
and save BIG! 





g COMMUNITY POLL 


What is your favorite color 











We will also see the blog sidebar block included by default on the right-hand side of 
our layout: 





BLOG 


Recent Posts 
Hello worid! 
Archives 

May 2009 


Categories 
Uncategorized 


RSS 


O Posts 
& Comments 
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Configuration 


Once the install process has finished, we head to our Magento administration system 
and to System->Configuration. We will now see a Blog sub-menu that controls our 
WordPress integration settings for this plugin. 





Configuration 





b GENERAL 
General 


Web 
Design 
tao ty used 











Under this new menu item, we will find all our configuration options for integration 
that the extension allows within Magento: 























Blog © Save Config 
Enable Wordpress Blog f Yes TA 
Require Login To View ! No | 
Require Login To Comment f No a 
Page Title | Blog 
Enable Footer Link f Yes E) 








Page Layout | 2 columns with right bar g] 


Wordpress Blog Menu A] 
Require Login To Show Í No Z] 


Menu 


Enable Right Menu | Yes K] 


Enable Archive Descriptions Í Yes BA 


Enable RSS links | Yes iw 
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Let's browse through the configuration values so that we could understand what 
each configuration value does. 


WordPress Blog Settings 





Configuration value What it does 

Enable WordPress Blog Enables or disables / bl 0g/ from working 

Require Login To View Requires log in to the Magento user system to view the 
blog, allows for private member news 

Require Login To Requires log in to the Magento user system to comment on 

Comment the blog 

Page Title Changes the page title when a user is accessing the blog 
URL on our Magento installation 

Enable Footer Link Puts the blog automatically into the footer links menu to be 
dynamically output if we call the function 

Page Layout Decides which Magento page template to use when 
showing the blog 


WordPress Blog Menu 


The following table illustrates the configuration values of a blog menu and what 
they do: 





Configuration value What it does 





Require Login To Show Menu Decides whether or not to show the sidebar to 
logged out members of our Magento installation. 


Enable Left Menu Determines whether or not the blog sidebar block 
shows in the left menu (when available) 


Enable Right Menu Determines whether or not the blog sidebar block 
shows in the right menu (when available) 


Enable Archive Descriptions If enabled, the user will see a statement similar 
to the following in the blog sidebar block, when 
browsing a blog archive on the site: You are 
currently browsing the blog archives for May, 
2009 


Enable RSS links Determines whether or not to show the links to 
your blog's RSS feeds in the blog sidebar block. If 
disabled, they disappear 
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It's advisable to configure these options (the way we need them now, rather than 
later) to make sure that everything is set up before we start tweaking the display. 
Doing so will display the following message:stop you have to come back later on. 


If we're going to use widgets in our sidebar, rather than editing the sidebar directly, 
it's recommend to turn off Enable RSS | inks to ensure that we don't have anything 
pre-appended to the sidebar widget output. 


Changing the display of integration 

The extension contains base templates which can we change to alter the display 
of the integration. Templates for the extension can be found in/ app/ desi gn/ 
frontend/default/default/templ ate/blog/. 


There are two templates in this directory for alteration: 
e blog. pht ml — For alteration of the blog page template 


e menu. pht ml —For alteration of the sidebar display 


Page/post layout 


The bl og. pht ml template doesn't consist of much display, only that of ani f / 
elseif/else statement to decide the template to be included. It does, however 
contain the output for the message: You must be logged in to view the blog if 
the option is enabled. 


The actual templating of the blog post look and feel is done within the WordPress 
theme and the magento. php template within the theme directory named ma gent o 
that we copied over earlier. Everything is templated the way a normal WordPress 
theme would be, besides the fact that we don't call get _header(),get_sidebar(), 
orget_footer() in our templates. 


The default magento. php template also uses <?php wp_reset_query();?>, which 
must stay at the top of the file no matter what edits we put in place. This function 
ensures compatibility with Magento and that no errors occur. 


Sidebar 


The menu. pht ml template consists of our sidebar block for display in our chosen 
Magento sidebar, if its turned on. It contains the archive description messages, a 
widgetized sidebar, and a non-widgetized sidebar. 


This means that it will have a default display if we're not using widgets. However, 
if we use widgets, then it will set a default set of content to display below the 
widgets that we select. 
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Let's take this sidebar widget set up as an example; we've put the following 
widgets into our sidebar under Appearance->Widgets under the WordPress 


administration system: 


Pages 

Links: Blogroll 
Meta 

Search 


Recent Posts 


The end result on both the WordPress configuration and the Magento display is 
shown in the following screenshots: 














Current Widgets 


Í Sidebar 1.) Show 


You are using 5 widgets in the sidebar. 


Add more from the Available Widgets section. 


Pages 


Links: Blogroll 


@ BLOG 


Pages 
About 


Blogroll 


Development Blog 


Documentation 
Plugins 
Suggest ideas 
Support Forum 
Themes 


WordPress Planet 


Log in 
Entries RSS 


( Search ) 


Recent Posts 
Hello world! 
RSS 


& Posts 
A Comments 
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Here, we notice that the RSS feeds are automatically placed at the bottom as the 
Enable RSS links option is set to Enab| ed within Magento. Otherwise, we have a 
perfect display and control for our blog sidebar widget throughout the site. This 
widgetized sidebar will also stay active throughout the site, not just on / bl 0g/. 


Other content management systems 


There are numerous other content management systems (not covered directly in this 
book) that can integrate very well with Magento. All these are publically available 
modules, either for sale or free download, to integrate their systems with Magento. 
Most of these are third party and their quality has been ensured, prior to their 
inclusion in this section of the chapter. 


Typo3 
Typo3 was founded in 2004 and is defined as a professional Web Content 
Management Framework. It is an open source system and has an estimated install 


base of 290,000 websites. 


TypoGento http://www. typogento. com allows for Magento integration into Typo3. 
It uses both an extension for Typo3 and an extension for Magento to make it work. 
However, it permits us to install Magento as a component of Typo3 and to display 
our store seamlessly within Typo3. It uses the Typo3 user system and allows for 
seamless template customization. 

















There is an excellent guide available on how to install TypoGento 

-2 

GA available athttp:// www. typogento.com/need-a-docu/how-to- 
install-typogento. html. 


Drupal 


Drupal is an open source content management system that allows an individual or 
community to easily publish, manage, and organize a wide variety of content ona 
website. Tens of thousands of people and organizations are using Drupal to power 
scores of different websites. 
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ee, Drupal 


Magento integration with Drupal has been put forward for the Google Summer 
of Code as an idea: htt p:// drupal. org/node/ 236456. Itis yet to be seen how 
significant the idea will be, but it seems like it is gaining some traction in the 
Drupal community. 











ExpressionEngine 

ExpressionEngine is a flexible and a feature-rich content management system that 
empowers thousands of individuals, organizations, and companies around the world 
to easily manage their websites. 


ce) ExpressionEngine® 





eeCommerce (http: //eecommerce. com) implements its own mammoth web 
services framework to vastly expand the Magento web services API for enabling it to 
integrate Magento into ExpressionEngine entirely. It currently lists its feature set as a 
complete solution to integration with ExpressionEngine and Magento. 


Joomla! 


Joomla! is an award-winning and one of the most popular online CMS today. Joomla! 
is also open source and offers a mass variety of extensions, with the current catalog 
standing at 4400 extensions. 


$ Joomla! 





M 


n source mi 
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Magento bridge (http: //opensource.jira.nl/projects/ magento- bridge) adds 
a bridge between Joomla! 1.5 and the Magento e-commerce platform. It not only 

allows for displaying Magento content within the Joomla! component area, but also 
ships with Joomla! modules and Joomla! plugins. It's available for purchase at €195. 


The bridge uses two types of extensions: on the Joomla!-side a backend component 
helps us to configure the bridge, while a frontend component shows the Magento 
content inside the Joomla! component area. Joomla! modules are used to show the 
Magento shopping cart somewhere within our Joomla! template. Also, plugins are 
available to allow for further integration (search the catalog, user synchronization, 
and so on). 


On the other side, there is a Magento module which is called through web services. 
This not only allows for flexible development, but also to have Joomla! and Magento 
installed on separate servers. 


Summary 
That's the end of our integration of third party content management systems chapter. 
In this chapter, we have gone through the following: 

e How to install the WordPress extension 

e How to configure the WordPress extension 

e Configuring Magento's display of the WordPress extension 


e Changing the look and display of your templates for the WordPress 
integration 


e Which other third party CMS integration packages and extensions for 
Expression Engine, Drupal, Typo3 and Joomla! are available 


Now, you can practice the integration of Magento for your chosen content 
management systems. Try it out with WordPress as a starter, and maybe give one 
of the other packages (highlighted towards the end of this chapter) a go and see 
how they work out for you! 
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In this chapter, we'll be covering one of the most documented features of Magento by 
Varien. Bundled with any default installation of Magento comes a web services API 
that allows interaction of third party applications and scripts, with several sets of 
core data. We can use either SOAP or XML RPC protocols to execute Core API calls 
for interaction with those available in the system. 


In this chapter, we will go through the following: 


What the Core API actually does 

What it can be used for 

What APIs we have available to us 

Setting up API access for our scripts 

What methods of using the API we have available to us 
The methods and functions the Core API has available 
Common errors in the API 


A sample implementation of the customer API for creating, updating, 
deleting, and retrieving customer data from within Magento 


What is the Core API? 


The Core API is Magento's bundled API (Application Programming Interface) that 
comes with a default installation. It enables us to build applications that interface 
with the Customer, Product, and Order data in any Magento installation. 


Magento's Core API 





Which Core APIs are included? 


Eighteen APIs currently exist in the system: 


Customer API 
Customer's Groups API 
Customer Address API 
Country API 

Region API 

Category API 

Category Attributes API 
Product API 

Product Attributes API 
Product Attribute sets API 
Product Types API 
Product Images API 
Product Tier Price API 
Product links API 
Order API 

Shipment API 

Invoice API 

Inventory API 


What do the Core APIs do? 


Each API allows us to retrieve, insert, update, or delete data belonging to the 
appropriate data group with direct code access. This allows us to interface with 
data by integrating with our thirdparty script or content management system. 


Covering everything from customer data to invoicing and shipping to product data, 
each API has its own purpose. The APIs are gathered into groups that each have 
their purpose: 


Customer — For import/export of customer details and addresses 
to/from Magento 
° Customer API 


Customer's Groups API 
° Customer Address API 
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e Directory — Retrieving country/regions from within Magento 
° Country API 
° Region API 


e Catalog—For import/export of categories and products to/from Magento 
° Category API 
° Category Attributes API 
° Product API 
° Product Attributes API 
° Product Attribute sets API 
° Product Types API 
° Product Images API 
° Product Tier Price API 
° Product Links API 


e Sales—Import/export of orders to/from Magento 
° Order API 
° Shipment API 


° Invoice API 


o 


Inventory API 


Prerequisites to using the Core API 


The API can be used out of the box as soon as Magento is installed. The only thing 
required for using the API is user permission, set up in the system for authentication. 
An account is set up before any script accesses the given APIs. Later on, our script 

is able to execute all API calls, using the authorization set up (this will be covered in 
detail later). 
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Examples of what can be done with 
the Core API 


There are several interesting implementations of the Core API that could be 
developed into thirdparty CMSs, such as: 


e Automatic stock updates from the system to a thirdparty application 


e Creating a customer record, invoice, shipment, and updating stock inventory 
online when an order is placed off-line 


e Building an import script for all products, customers, and order data (but not 
for orders themselves) from an old database or an e-commerce installation 


e Automatically syncing stock inventory into the system, when Excel or CSV 
files are not available 


Giving scripts access to the Core API 


In order for our scripts to use the Core API, we need to have an authorization from 
Magento. This involves setting up an API user and API key to be passed to Magento, 
in order to be allowed to access the API(s) that we would want to use with the script. 


Let's start by setting up a role for our API user. A role is Magento's term for a set of 
access permissions. For example, Administrator and Customer are two different 
roles in the standard Magento user system. Here we define our roles in terms of 
which resources and methods a user could execute in the system, once authenticated 
in the Core API. 


We start by logging into the Magento administration system and going to 
System->Web Services->Roles, as seen in the following screenshot: 
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Magento Connect 


Cache Management 








A blank table of roles will be shown initially, as there will be none setup in a default 
Magento installation. If the roles have been setup beforehand, then we will see roles 
on the page. 





Roles 
Page 1 of 1 pages | View Cg per page | Total 0 records found | Reset Fitter | Search | 
ID + Role Name 





No records found. 











We click on Add New Role in the upper-right of the previous screen. 





Role Information Add New Role ` Back | 
Role Info 
ae 
ee ae CRER 
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We will immediately see a page that asks for our new Role Name. Let's call this one 
Complete Access. Now that we have a name, it's time to assign resources which the 
role will be allowed to execute when it's connected to our API. 


We click Role Resources in the left sub-navigation menu to bring up the complete 
list of resources available which could be assigned to our new role. In this case, we'll 
select All from the Resource Access drop-down list (at the top of the page) to give 
our API role complete access to all resources. 


Resource Access | All =] 














For limiting the role that we're creating (in any way), we can keep the Resource 
Access drop down on Custom and tick the boxes applicable to the resources that we 
would like our role to gain access to, when assigned to a user. 





Resources 


o 
by 


-M Catalog 
a E4 Product 
L- C Retrieve products data 
Li N Create 
| | C Update Tier Price 
E O Update 
L m Delete 
aL p Product Attributes 
L i C Change or Retrieve attribute store view 
— —) Retrieve attribute data 
(5 [A Link (Related, Up sell, Cross sell) 
L |) Remove 
— 0 Update 
L1 Assign 
al © Product Images 
_ C Remove 
— E Update 
L M Create (Upload) 
a E4 9 Category 
Ca f Retrieve categories tree 
|) m) Retrieve category data 
E O Create 
(|) Delete 
= C Move 
Li m Update 
aL Assigned Products 
La 0 Remove 
Ei | Update 
LCi Assign 
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In this example, however, we'll select All from the Resource Access drop down. We 
click Save Role in the upper-right of the page and head back to our roles index (as 
we did before). We will see our newly created role on the page. 





Roles © Add New Role 


Page 1 of 1 pages | View Eg) per page | Total 1 records found od E 


ID + Role Name 





1 Complete Access 








Next, let's head on over to create the API user to whom this role will apply. We'll go 
to System->Web Services->Users. The No records found screen will be displayed 
unless users have been created previously in the system. 





Users © Add New User 
Page 1 of 1 pages | View Res per page | Total 0 records found | Reset Fitter | Ea 
ID | User Name t First Name Last Name Email Status 
=—_ 
No records found. 











We click Add New User in the upper-right side of the screen and progress to the add 
New User screen. 








User Information New User Back | Reset | O Save User 
User Info 
User Role Account information 
User Name * 
First Name * 
Last Name * 
Email * admin 
Api Key * seseuseseeees 


Api Key Confirmation * 


This account is | Active Z 





In this screen, we'll be able to set our User Name and Api Key, required to interface 
with the API. We can also set our personal information such as First Name, Last 
Name, and Email. We also have a setting to deactivate the account, (if we ever want 
to) without deleting it, but for now let's keep it active. 
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We set values to the following, as this will be used as an example later in the chapter: 








Field name Field value 

User Name Magentobook 

First Name Magento 

Last Name Developer's guide 
Email me@jhuskisson.com 
Api Key Developersguide 
Api Key Confirmation Developersguide 
This account is Active 





Once the details are filled in, we click on User Role from the sub-menu on the left of 
the screen and choose the role we created earlier, for our new user. 














Page 1 of 1 pages | View 20-4] per page | Total 1 records found | Reset Filter | | Search | 
Assigned Role Name 
| Any E) 
w Complete Access 
Next, we click Save User for the successful creation of our API User Name and 





API Key for later use in this chapter. Just for full confirmation, we head back to 
the System->Web Services->Users page to see our new user account appear with 
all its details. 








Users Forano) 
Page 1 of 1 pages | View 20) per page | Total 1 records found |Search | 
ID User Name t First Name Last Name Email Status 


1 Magentobook Magento Developer's Guide me@jhuskisson.com Active 








Now that we're done, we can start experimenting with the API and begin using the 
methods available to us. 











[194] 


Chapter 9 





Choice of protocols 


Magento provides a couple of choices for the protocol to use with its Core API; 
these are: 


e SOAP 
e XML RPC 


It's a matter of choice between the two. A few of us would simply decide on preference 
from previous usage, while some may not be able to use one of the protocols and end 
up using the alternative. The following information introduces us to both of them, so 
that we can choose between the two protocols. 


SOAP 


SOAP is the newer standard of the two and the most popular. It is also faster in 
comparison and should be our default choice of protocol, if it is available to us. 


— More information about the SOAP protocol and its history can be found 
GA at: http://en. wikipedia. org/ wiki / SOAP orat its official site 
http://www. w3.org/TR/soap/. 


Checking for SOAP installation on the server 


Before we're able to use SOAP on our server and therefore use SOAP as the method 
of interacting with the API, we need to make sure that we have the SOAP PHP 
extension installed on the server. 


To do this, we create a file called phpinfo.php and place the following inside it: 


<?php 
phpinfo(); 
?> 
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We can save, upload, and access the file directly by inserting the public URL to 

this file in our browser. Once accessed, we'll see our server's core setup information 
laid out in front of us, to be devoured! We'll have a look at the following screen 
titled soap. 





soap 














Firstly, we'll look for the fact that this SOAP block actually appears. This means that 
SOAP is installed on the server. If it isn't installed, we'll have to contact our web host 
or server administrator to get the SOAP PHP extension installed before continuing. 
If this isn't available to us as an option, we'll have to install XML RPC as the chosen 
protocol for interacting with the Magento Core API. 


Secondly we'll look inside the block at the first setting Soap Client. This shows 
whether or not we're able to execute SOAP clients from our web server. If set to 
enabled, it means that it is installed and we can go ahead with using SOAP as the 
method of choice. If set to disabled, we'll need to contact our web host or web 
administrator and make sure that they set it to enabled. 


Putting SOAP to use 


If the SOAP PHP extension is installed and enabled on our server, then we'll be 

able to use the SOAP API provided by the Magento Core API without any external 
libraries of any kind. Magento's Core API documentation outlines a basic example of 
usage, shown below: 


$client = new SoapClient('http:// example.com/api/soap/?wsdl'); 


// If somestuff requires api authentification, 

// we should get session token 

$session = $client->login('apiUser', ‘apiKkey'); 

$result = $client->call($session, 'somestuff.method'); 
$result = $client->call($session, ‘somestuff.method', ‘argl'); 
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$result = $client->call($session, '‘somestuff.method', array('argl', 
‘arg2', ‘arg3')); 
$result = $client->multiCall($session, array( 
array('somestuff.method'), 
array('somestuff.method', ‘argl'), 
array('somestuff.method', array('argl', ‘arg2')) 
DE 


// If you don't need the session anymore 
$client->endSession($session); 


The key line is the first one, which defines our SoapCl i ent for usage of the API: 
$client = new SoapClient('http://example.com/api/soap/?wsdl'); 


Between the SOAP and XML RPC implementation (in terms of code), this last line 
is the only line that is different. It is used to initiate the connection to the Magento 
Core API and attach an instance of the Core API class to the $c! i ent variable. For 
example, the function cal | () will now be accessed via $cli ent- >call(), now 
that this variable is assigned properly. We must ensure to use the IP address of our 
computer (rather than | ocal host), if we encounter issues, as some versions of PHP 
are affected by a problem which stops this call from working properly. 


Zend Framework SOAP Client 


If we prefer using Zend Framework for everything to retain consistency throughout 
all of our code in development with Magento, then Zend Framework has a SOAP 
Client class. We could use it with Magento Core API, available at the following URL: 


http: //framework.zend.com/manual/en/zend.soap.client. html. 


XML RPC 


XML RPC is a fantastic fallback, if SOAP is not available on our web host. Although 
it's slightly slower, it's by all accounts a very solid protocol for accessing the Core 
API.. By no means is it a different set of code or executions from SOAP. 


2 More information about XML RPC and its history can be obtained at 
Ka http: //en. wikipedia. org/ wi ki/ XML- RPC orat its official site 
http://www. xml rpc. com. 
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Getting XML RPC on our server 


With XML RPC, there's no need to install anything on our server to get it to work. 
With our implementation, we'll work with Zend Framework's XML RPC client class 
to simplify things across the board. What this class does for us is that it provides 

an exact match of the SOAP interaction of calling methods and brings consistency 
between the methods of using the API. 


& "More about Zend Framework XML RPC class can learned at: 
Sp 
http: //framework.zend.com/ manual/en/zend.xmlrpc. htm. 


Setting up the Zend Framework XML RPC class 


Before we can use anything related to XML RPC, we need the Zend Framework 
XML RPC class. We'll be using this particular class for two reasons: 


1. For consistency between code from Magento and custom modules 


2. Simply to make sure that we're using the same framework for everything 
throughout book 


We can still use whichever class we choose to with the XML RPC API, as it isn't 
limited to the class we're using to interact with it. 


We start by heading over tohttp://framework. zend. com/ downl oad/current/ 
and downloading the minimal package with just the Zend Framework files. We 
would not want any tests, demos, or Dojo Toolkit clogging up our time when 
uploading afterwards. 





Full Contains Zend Framework, Dojo Toolkit, all demos, and 
Package all tests. Start here if you don't have a preference. 


Contains only the components in the Zend Framework 


a Minimal Standard Library. This is a smaller package for those 
Package who know they don't need all of the items in the full 
package. 
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Once we have the minimal package, we place the extracted Zend directory in the 
same directory as the planned script that will use the Magento Core API. We use 
the following lines of code for including the class: 


require_once 'Zend/Xml Rpc/Client.php'; 


This will give us everything that we need to start putting the Magento Core API 
XML RPC protocol to use. 


Putting XML RPC to use 


Magento's provided XML RPC documentation is as follows: 


$client = new Zend Xml Rpc_Client('http://example.com/api/xmlrpc/'); 


// If somestuff requires api authentification, 
I] we should get session token 


$session = $client->call('login', array('apiUser', ‘apikey')); 
$client->call('call', array($session, '‘somestuff.method' 
array('argl', ‘arg2', ‘arg3'))); 
$client->call('call', array($session, ‘somestuff.method', ‘argl')) 
$client->call('call', array($session, '‘somestuff.method')) 
$client->call('multiCall', array($session, 
array 

array('somestuff.method', ‘argl') 

array('somestuff.method', array('argl', ‘arg2')) 

array('somestuff.method' 





HS 


II If you don't need the session anymore 
$client->call('endSession', array($session)); 


The important line of this example is the initial one: 
$client = new Zend Xml Rpc_Client('http://example.com/api/xmlrpc/'); 


This is the only line that is different from the SOAP protocol example in the code. 
This is what initializes the XML RPC connection to the Magento Core API and allows 
us to start executing calls to interact with Magento. 
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Basic API methods 


Magento provides a set of methods, or functions, that we can use once we have our 
API $cli ent set and ready to use. These methods are the standard for performing 
calls to the Core API and are the standard for using the Core API with your scripts. 


Describing the methods 


Here are the Basic API methods as outlined by Magento's Core API guide 
introduction page: 








Method Description Return 
value 
startSession() starts API session and returns string 
sessionid 
endSessi on(sessi onl d) ends API session boolean 
login(apiUser, api Key) starts API session, returns $es$i onld string 
and authorizes api Us er 
call(sessionid, calls API resource that is allowed in Mixed 
resourcePath, array current session (if no session is specified, 
arguments) you can call only resources that are not 
protected by ACL) 
mul tiCall(sessionid, calls API resource's methods that are array 
array calls, array allowed for current session (if no session 
options) is specified, you can call only resources 


that are not protected by ACL). If br eak 
option is specified, mul ti Cal | breaks 
on first error 


resources(sessionld) returns list of available API resources array 
and methods allowed for current 
session. 


global Faults(sessionld) returns list of fault messages and array 
their codes that do not depend on any 
resource. 


resourceFaults(sessionid, returns list of the specified resource fault array 
resourceName) messages, if this resource is allowed in 
current session. 
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Understanding the methods individually 


We'll go through these methods individually, so that we can properly understand 
them before moving forward. 


The following methods are designed to be used separately in each of the code 
examples given. We must remember to separate them and not combine them one 
after the other, when trying them out for the first time. 


startSession() 


This method is used to start a session where API authorization isn't required to access 
a resource. It's a great option for those building their own APIs for modules, that allow 
sharing the Magento installation's data with anyone who wants to work on the API. 


A sample usage is as follows: 


11 API opening 

$session = $client->call('startSession'); 
// API calls and other actions 

II Ending of the session 


The $session variable is populated with our session ID for use later with other 
methods and throughout the rest of the script, though in this scenario we won't have 
many resources to work with. We can try calling the resources method, to see just 
how many we can access. 


endSession(sessionld) 


Used to end the API session at the end of our script, to make sure that the API 
session has been ended properly. 


A sample usage is described below: 


I1 API opening 

// API session start 

// API calls and other actions 
$client->call('endSession', array($session)); 


This would be placed at the end of our API usage script. The variable $s essi on 
would be set either via the st art Session() method or returned via the login 
method at the start of our script. This array is then passed to our endSessi on( ) 
method at the end of the script. It's important to end sessions for cleaning up the 
data that is being stored while the session is in progress. 
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login(apiUser, apiKey) 
This method is used to authenticate your script with Magento using your API user 
and key. 


The following is a sample of its usage: 


[1 API opening 

$session = $client->call('login', array('Magentobook', 
'Developersguide')); 

I1 API calls and other actions 

II Ending of the session 


The $sessi on variable is populated with our session ID for use later with other 
methods and throughout the rest of the script. 


call(sessionld, resourcePath, array arguments) 


This is used to call API methods one at a time; it is likely to be the most popular 
method that we will use, while working with the Magento Core API. The following 
examples demonstrate its usage. 


Example one, no arguments needed for a call: 


Scustomers = $client->call($session, ‘customer.list'); 
Example two, single argument for a call: 

Sclient->call($session, ‘customer.delete', $Customerld) ; 
Example three, multiple arguments for a call: 


$calls = array( 
array( ‘catalog product.info', 1), 
array( ‘catalog _product.info', 2 ), 
array( ‘catalog _product.info', 3 ), 
Jy 
gresults = $client->multiCall( $session, $calls ); 
We notice that the $s essi on variable is required for all calls, and that a called 


function is executed in the format of: $cl i ent- >cal | ($session, $resource, 
$arguments); no matter which variation of the method is being used. 
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multiCall(sessionld, array calls, array options) 


This is used for batch calls, if ever required. It is similar to the previous call method, 
but is used for calling several methods at the same time. 


It can be used as follows: 


$client->call('multiCall', array($session, 
array( 
array('somestuff.method', ‘argl'), 
array('somestuff.method', array('argl', ‘arg2')), 


array('somestuff.method' ) 


)); 


This method is best used when mass updating records or if we like to tidy up 
multiple actions into one statement. For example, when inserting an order with a 
shipment and invoice all at the same time while importing from another installation. 


resources(sessionld) 


This method returns a list of the available methods relating to the current session. 
The following is an example of its usage: 
$resources = $client->resources($sessi on); 


This will return an array of available resources to our current session. Jisse Reitsma 
of Jira ICT wrote the following code to produce a simple output of all the resources 
and methods returned by the method, which helps us visualize the output better: 


<?php if( is_array( $resources ) && !empty( $resources )) { ?> 
<?php foreach( $resources as $resource ) { ?> 
<hl><?php echo $resource['title']; ?></hl> 
Name: <?php echo $resource['name']; ?><br/> 
Aliases: <?php echo implode( ',', $resource['aliases'] ); ?> 
<table> 

<tr> 


<th>Title</th> 
<th>Path</th> 
<th>Name</th> 
</tr> 
<?php foreach( $resource['methods'] as $method ) { ?> 
<tr> 
<td><?php echo $method['title']; ?></td> 
<td><?php echo $method['path']; ?></td> 
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<td><?php echo $method['name']; ?></td> 
<td><?php echo implode( ',', $method['aliases'] ); ?></td> 
</tr> 
<?php } ?> 
</table> 
<?php } ?> 
<?php } ?> 


This call is useful when debugging the existing session and can save a lot of heartache 
when trying to figure out why a resource or method is not executing properly! 


globalFaults(sessionld) 


This method returns global faults with our API usage. It's useful for seeing which 
global API faults are occurring, if anything goes wrong. The complete list of these 
faults can be found later in this chapter. 


It is used as follows: 
$faults = $client->globalFaults($session); 


This sets $f aul ts to an array of the global faults currently occurring. You can then 
use aforeach() function to get the faults out of the array for a comfortable display 
and easy reading. 


resourceFaults(sessionld, resourceName) 


This returns faults for a specific resource. 
It is used as follows: 
$faults = $client->resourceFaults($session, ‘resource. name'); 


This then sets an array of faults for the resource. name resource to the variable 
$f aul ts , on which we can then use the f or each() function for reading on the 
front end. 
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Global API Faults 


The following are global Core API fault codes that can be returned, no matter what 
Core API is being used or which call we execute. These errors apply to each Core API 
call available. The support guide outlines them as follows: 








Fault Code Fault Message 

0 Unknown Error 

1 Internal Error. (For details, we can read the log file) 
2 Access denied 

3 Invalid API path 

4 Resource path is not callable 

5 Session expired, re-login 





These will be directly in PHP error format, if the server allows error reporting when 
they occur, as shown below: 





Fatal error: Uncaught SoapFault exception: [2] Access denied. in /Applications/MAMP/htdocs/api-scripts 
/api.php:5 Stack trace: #0 [internal function]: SoapClient->__call(‘login', Array) #1 /Applications 
/MAMPYhtdoes/api-scripts/api.php(5): SoapClient->login(‘incorrect-usern...', 'incorrect-passw...') #2 
{main} thrown in /Applications/MAMP/htdocs/api-scripts/api.php on line 5 











In the following table, we can see what these errors are and why they occur: 





Fault Code Reason for fault 


0 This error is rare and it normally means something extraordinary has 
gone wrong. 





1 If we read the log, we will come to know exactly what has gone wrong to 
cause this error. 


2 When we called | 0 gi n, we passed an incorrect API user and key 
combination or the API key and user that we passed to the method does 
not have rights to call the API method that we're trying to execute. 


3 The API path that we had called at the start of our script is invalid and 
does not exist. 


4 The resource that we're trying to call in our function is not callable by 
our API key and user, or simply does not exist. 


5 Our API session has expired and we need to log in again. 
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In the following table, we have the two fault tables together for a quick overview: 








Fault Code Fault Message Reason for fault 

0 Unknown Error This error is rare and it normally means something 
extraordinary has gone wrong. 

1 Internal Error. Please If we read the log, we will come to know exactly what 

see log for details has gone wrong to cause this error. 

2 Access denied When we called | 0 gi n, we passed an incorrect API 
user and key combination or the API key and user 
that we passed to the method does not have rights to 
call the API method that we're trying to execute. 

3 Invalid API path The API path that we had called at the start of our 
script is invalid and does not exist. 

4 Resource path is The resource that we're trying to call in our function 

not callable is not callable by our API key and user, or simply 
does not exist. 

5 Session expired, Our API session has expired and we need to log in 


re-login 


again. 





Basic API scripting: Customer API 


We start with some basic API scripting to ease us into the operations of the Magento 
Core API, starting with the Customers API. 


Getting started 


Most of us would be using SOAP, but this is easily interchangeable with XML RPC 
(as mentioned earlier in the chapter). We start by setting up our connection to the 
API, creating a file called api . php, and placing in it the following: 


<?php 
$client = new SoapClient('http://m.j huskisson.com/api/soap/?wsdl' ) 
$session = $client->login('Magentobook', '‘Developersguide'); 


$client->endSessi on($session); 


?> 


Once we've loaded it into our browser, we'll see a blank screen which means that 
everything is working nicely. 
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Creating a customer 

We start by creating a customer in our database; we have data in our default 
Magento installation at the moment. Hence, we'll need to insert customers before 
we have any data to retrieve or update. Between our | ogi n() andendSessi on( ) 
functions we'll enter: 


$customer|nfo = array( 


‘firstname’ => 'First', 

‘lastname’ => 'Last', 

"emai |' => 'test@example.com, 
‘password hash' => md5('password'), 
‘store id' => 0, 


‘website_id' => 0 
E 


$newCustomerid = $client->call($session, 'customer.create', 
array($customerlnfo)); 


We reload our file in the browser and it should take slightly longer to load, but will 
still return a blank screen. However, if we take a look at the Manage Customers 
screen under Customers->Manage Customers in the Magento administration, we'll 
see that the new customer has been created successfully. 








@ Manage Customers 
Page 1 of i pages | View 20) per page | Total 1 records found Export to eo AEA | Reset Filter | |" Search | 
Select All | Unselect Ali Select Visible Unselect Visible | 0 items selected Actions se | | Submit "| 

10 + Name Email Group Telephone zip Country State/Province Customer Since Action 
Anya] From: | kH | All colle | From: =] 
To: To: |F] 
o 1 First test@example.com General 25 May 2009 16:37:40 Edit 
Last 











We'll also be able to log in as this newly created customer with the e-mail and 
password inserted straightaway. 
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Retrieving an individual customer's details 


Now that the customer is in the database, we can retrieve the fictional customer's 
details using the customer. info call and the ID of that customer. For example: 


$customerld = 1; 
$customerlnfo = $client->call($session, ‘customer.info', $customerld); 
print var_dump($customer| nfo); 


Once we save our file and reload the page, we'll see an array output with all the 
variables applicable to this customer's core data. 


array(12) { 

"customer _id"]=> string(1) "1" 

"created at"]=> string(19) "2009-05-25 16:37: 40" 
"updated at"]=> string(19) "2009-05-25 16:37: 40" 
"increment _id"]=> string(9) "000000001" 

"store id"]=> string(1) "0" 

"website id"]=> string(1) "0" 

"created in"]=> string(5) "Admin" 

"email "]=> string(16) "test @example. com" 
"firstname"]=> string(5) "First" 

"group_id"]=> string(1) "1" 

"lastname"J=> string(4) "Last" 

"password hash"]=> string(32) "5f4dcc3b5aa765d61d8327deb882cf 99" 

















Updating the customer's details 


We can use this how we like. In our current situation, we can change the name of 
this customer via the API, assuming that we have updated it elsewhere away from 
Magento. To do this, we should use the following code: 


$newCustomer| nfo = array/( 
'firstname' => 'Updated', 
‘lastname! => 'Customer' 
|; 


$client->call($session, 
"customer.update', 
array($customerld, $newCustomer| nfo) 
E 


var_dump($proxy->call($session, 'customer.info', $customerld)); 
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This will update our customer and print out his new details for us to confirm that it 
works. If our script has worked, we'll see the customer record updated in Magento, as 
well as a new array printed out of the customer's data that shows the new information. 


Listing all customers from the database 


In some cases, we may need to get several customers out of the database rather than 
just the one. Maybe we're inserting the information from the customer database of 
Magento into another database or need to use it in some way. Magento's Customer 
API provides a simple way of doing this, as follows: 


$customerList = $client->call($session, '‘customer.list'); 


This will return an array of all customers in the database, for us to process through. 
It will output exactly how customer. info outputs, but in separate arrays for each 
customer returned via the method. 


Deleting a customer from the database 


Lastly, if we want to delete a customer record from the Magento database there's a 
method available, (provided we know the customer ID): 


$client->call($session, ‘customer. delete', $customerlD); 


It's as simple as that; the customer with the ID contained in the $c ust omer | D 
variable will be deleted from the database. 


Complete list of available resources and 
methods 


The following is a complete list of all the available resources, APIs, and methods in 
the Magento Core API for quick reference. 


For full reference with example code for each of the APIs, we can visit: 
Se http://www. magentocommerce.com/wiki/doc/webservices- 
api/api online. 
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Customer methods 


For handling of customer information in Magento's database, the following methods 
are available: 








Customer API Customer Groups API 
Resource name: customer Resource name:customer group 
customer. list —Retrieve customers customer group.|ist — Retrieve 


customer's groups 
ustomer. create —Create customer 


a 


ustomer. info —Retrieve customer data 


a 


a 


ustomer. updat e —Update customer data 





ustomer. del ete —Delete customer 
Customer Address API 
Resource name:customer address 


ustomer address.list —Retrieve 
customer addresses 


a 





a 


a 


ustomer address. create —Create 
customer address 


a 


ustomer address. info —Retrieve 
customer address 


a 


ustomer_ address. update — Update 
customer address 





customer address. del et e — Delete 
customer address 





Directory methods 


For retrieval of regi on and country i nf or mati on from Magento's database, the 
following methods can be used: 








Country API Region API 
Resource name: country Resource name: r egi on 
country. Ii st — List of countries region. list — List of regions in 


specified country 
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Catalog methods 


For handling catalog-related information in Magento's database, we have: 





Category API 
Resource name: category 


category. current St or e —Set/Get current 
store view 


category. tree — Retrieve hierarchical tree 
category.|evel — Retrieve one level of 
categories by website/store view/ parent 
category 

category. info — Retrieve category data 
category. create — Create new category 
category. update — Update category 
category. move — Move category in tree 
category. del ete — Delete category 
category. assignedProducts — Retrieve 
list of assigned products 

category. assignProduct — Assign 
product to category 

category. updateProduct — Update 











assigned product 

category. removeProduct — Remove 

product assignment 

Category attributes API Product API 
Resource name: category_attribute Resource name: pr oduct 
category_attribute. currentStore— product. current Store —Set/Get 
Set/Get current store view current store view 
category_attribute. |i st — Retrieve product. li st —Retrieve products 
category attributes list by filters 
category_attribute. options — Retrieve product. info —Retrieve product 
attribute options product. create — Create new 


product 
product. update — Update product 


product.setSpecial Price —Set 
special price for product 


product. getSpecial Price —Get 
special price for product 


product. del et e — Delete product 
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Product attributes API Product attribute sets API 

Resource name: product attribute Resource name: product _ 
attribute set 

product _attribute.currentStore— product attribute set. list — 

Set/Get current store view Retrieve product attribute sets 

product _attribute.list — Retrieve 

attribute list 


product attribute. options — Retrieve 
attribute options 








Product types API Product Images API 

Resource name: product type Resource name: product _ 
attribute media 

product_type.list —Retrieve product product _attribute_media. 

types current Store —Set/Get current 
store view 


product attribute media. 

| i st — Retrieve product image list 
product attribute media. 

i nf 0 —Retrieve product image 
product attribute media. 
types —Retrieve product image 
types 
product _attribute media. 
create — Upload new product 
image 
product attribute media. 
update — Update product image 
product attribute media. 
remove —Remove product image 
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Product Tier Price API Product links API 
Resource name: product _attribute_ Resource name: pr oduct_!ink 
tier _price 

product _attribute tier price. product_link.|ist —Retrieve 
i nf 0 —Retrieve product tier prices linked products 

product attribute tier price. product_link. assign —Assign 
updat e — Update product tier prices product link 


product_link. updat e —Update 
product link 


product_link. remove —Remove 
product link 


product _link.types —Retrieve 
product link types 








product_link. attributes — 
Retrieve product link type attributes 





Sales methods 


For invoices, shipments and credit memos in Magento's database, we have: 





Order API Shipment API 

Resource name: or der Resource name: order _ shi pment 
order. list — Retrieve list of ordersby  order_shi pment. li st —Retrieve list of 
filters shipments by filters 

order. info — Retrieve order order_shi pment. info — Retrieve 
information shipment information 


order. addComment — Add comment to order_ shipment. create — Create new 
order shipment for order 


order. hol d — Hold order order_shi pment. addComment — Add new 


comment to shipment 
order. unhol d —Unhold order 


order_shi pment. addTr ack — Add new 


order. cancel —Cancel order tracking number 


order_shi pment. removeTr ack — Remove 
tracking number 








order shipment. getCarri ers — Retrieve 
list of allowed carriers for order 








[213] 





Magento's Core API 








Invoice API 
Resource name: or der invoice 





order_invoice.|ist —Retrieve list of 
invoices by filters 
order_invoice.info—Retrieve 
invoice information 

order_invoice. create —Create new 
invoice for order 

order_invoice. addComment —Add 
new comment to shipment 
order_invoice. capt ur e —Capture 
invoice 
order_invoice. voi d — Void invoice 


order_invoice. cancel —Cancel 
invoice 








Inventory methods 


For updating of stock and inventory for products in Magento's database, we have: 





Inventory API 

Resource name: product _ stock 
product stock_item.1ist —Retrieve 
stock data by product ids 


product _stock_item. update — Update 
product stock data 
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Summary 


In this chapter, we've learned about interacting with the Magento Core API and 
the mass database of data that Magento holds. It's certainly a great addition to the 
excellent e-commerce system that is Magento Commerce. 


We have gone through the following: 


What the Core API actually does 

What it can be used for 

What APIs are available to us 

Setting up API access for our scripts 

What methods of using the API we have available to us 
The methods and functions the Core API has available 
Common errors in the API 


A sample implementation of the customer API for creating, updating, 
deleting, and retrieving customer data from within Magento 


With this knowledge, we should be able to write scripts using the Magento Core API. 
We must take up the challenge of integrating with a third-party system, for testing 
our newly acquired knowledge of Magento Core API. 
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Importing and Exporting Data 


In this chapter, we will learn about the built-in method of getting your data in and 
out of Magento. Magento is delivered with a set of features aimed at making it 
easy to get certain types of data in and out of the system. With the import/export 
functionality, we can set up profiles which act as saved records, so that we can 
regularly import and export the same data. In practice, this means that if we wish 
to do that process regularly, then we can set up a profile which will ensure that we 
don't need to run the filters each time. We can then come back to this, which acts as 
a save point for all the settings set up previously for the data import/export action. 


Here we'll be looking at the profiles that are set up with the system by default, and 
how we can add our own for easy import/export of data. 


What kind of data can | export or import? 
Magento has the following default Import/Export data profiles that come with the 
default installation and what data they relate to: 

e Customer data (users who have signed up for the system) 

e Product stock data (product stock data only) 

e Product data (all attributes relating to products) 


RS It's worth increasing the value of the PHP max_execution_ti me 
Q directive, as product databases over 200-300 products will experience 
issues with script timeouts on certain web hosting. 


Importing and Exporting Data 





There are two types of files that can be used for import/export in Magento: 


e Excel Spreadsheet 
e CSV (Comma Separated Values) 


The typical process is as follows: 


PON PR 


Creating a new profile 


Choosing a data type 


Naming the profile and choosing direction (import/export) 


Configuring the data type (for example with CSV, we choose tabular or 
comma separated values) 


5. Choosing which type of system data we want to interact with (customers or 
products) 


Filtering this data to meet our needs 


Saving our work 


Running the profile to produce the desired result 


Developers can also export their profiles as XML, in order to advance them under the 
Advanced Profiles functionality that comes with Magento. If we'd like to advance a 
profile further than the profile builder tool allows, then we can export the profile as 
XML to tweak into an Advanced Profile with more advanced actions. 


An introduction to the interface 


Profiles can be found under the Import/Export menu, in System->Import/ Export-> 
Profiles. Initially, we'll see a screen displaying all the profiles that we have set up, as 





follows: 
Profiles © Add New Profile 
Page f ofi pages | View { 20 $. perpage | Total 6 records found a Eo 
ID | Profile Name Profile Direction Entity Type Store Created At Updated At Action 


6 import Customers 

5 Export Customers 

4 Import Product 
Stocks 

3 Import All Products 

2 Export Product 
Stocks 

1 Export All Products 





Import 
Export 
Import 


Import 
Export 


Export 


Customers 
Customers 


Products 


Products 
Products 


Products 


All Store Views 
All Store Views 
All Store Views 


All Store Views 
All Store Views 


All Store Views 


31 Mar 2008 01:32:54 
31 Mar 2008 01:32:54 
31 Mar 2008 01:32:54 


31 Mar 2008 01:32:54 
31 Mar 2008 01:32:54 


31 Mar 2008 01:32:54 


From: =| 


To: |B 


31 Mar 2008 01:32:54 
31 Mar 2008 01:32:54 
31 Mar 2008 01:32:54 


31 Mar 2008 01:32:54 
31 Mar 2008 01:32:54 


34 Mar 2008 01:32:54 
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The default profiles that come with Magento (shown in the previous screenshot) 
cover the Import/Export of Customers, Product, and Product Stocks. These will help 
us get started with the feature and can also act as a template for profiles that will be 
set up later. 


We start with opening Export Product Stocks, profile ID 2. At the bottom left-hand 
side of the screen, we see four sections: Profile Wizard, Run Profile, Profile Actions 
XML, and Profile History. These can be seen when exporting data; an additional tab 
named Upload File appears when importing data. 


The four sections can be summarized as follows: 
e Profile Wizard is where we set up the profile through an interface aimed at 
not having us do any of the XML involved with Advanced Profiles. 
e Upload File allows us to upload files to be executed through the profile. 
e Run Profile allows us to run the current profile, as it was last saved. 


e Profile Actions XML allows us to take the raw XML that makes up this 
profile and take it into the Advanced Profiles section for advancement with 
options that aren't available via the Profile Wizard interface. 


e Profile History shows us actions previously performed with this profile. 


Profile Wizard 


We will focus on the Profile Wizard, as it is where the core of the Import/Export 
profile feature is based. Let's run through our fields on this tab, which is the default. 


Profile Information 


Profile Information comprises the following components, shown in the screenshot: 


| Prof misah mation OO OES 








Name: * Export Product Stocks 

Entity type: Products zi 
Direction Export 7] 
Store: Default (Admin) Values bd 
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Name 


The name that we assign to our profile in order to locate it later on from within 
the system. 


Entity type 

This decides which fieldset we interact with for the profile. It takes the options, 
Products and Customers. For example, if we select Products, then the fieldset for 
Products from the selected store(s) will be loaded for interaction with the actions 
and methods as selected in the rest of the form. 


Direction 


This decides the direction of which we're using the data for the profile. For example, 
whether we'll be taking a file and importing the data using the profile, or we'll be 
taking the data output from the profile and exporting to a file. It takes the options 
Import and Export. 


Upon selecting Import for Direction, two additional fields will appear. Number of 
Records allows us to define how many records will be processed at a time, whereas, 
Decimal Separator defines what separates the fields in the file that is being used to 
import products. 


For example: 
Sample data row: store, manufacturer, andprice 


Decimal Separator is the comma (,) being used to separate data. 


Store 


This option allows us to filter the profile to a specific store in our Magento setup. 
Store-specific fields will be loaded and only this data will be interacted with. It will 
automatically use this store ID for any data being imported, so that there is no need 
to declare it in our file when importing. It has the following option: Default (Admin) 
Store - <list of all stores in your Magento setup>. 


Selecting Default (Admin) Store defines this as a global profile that applies to 
all stores, so the st ore field in our data will need to be set when importing to 
specific stores. 
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File information 


File Information consists of the following components, shown below: 





File Information 
Data transfer: Local/Remote Server F| 
Type: Local Server ~ 
File name: export_product_stocks.csy 
Path: var/export 
(Absolute path or Relative to Magento install root, ex. var/export) 











Data transfer 
Options: Interactive and Local/Remote Server. 


Interactive (available only for imports), allows us to upload files to be run through 
the Run Profile tab. 


Local/Remote Server enables us to fill out the fields to get the file from a source. 


Type 


Options: Local Server and Remote Server. 


Local Server: The file is located on the same server as our Magento installation or 
within Magento installation's directories. 


Remote Server: We need to connect to an FTP connection to either fetch our file for 
importing or to store our file after exporting. This will then save the exported file on 
another server, ready to be used by another system. Else, it will be fetched from an 
external server and then imported. 


When we select Remote Server , we will be asked to insert our FTP 
information for the connection. This must be filled in for the Remote 
Server connection to work. 
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Path 


Path is the relative path to the file that we use for the profile, minus the trailing 
slash. It should always be / var /i mport_folder,rather than/var/import_folder/. 
There is no need to put our entire root address into the import directory here, just 
the part after the Magento root directory. If we have it installed in/root/address/ 
magento/, then our path will always be automatically prefixed with this by Magento. 


File 
File name is the name of the file once in this directory, with file extension, for 
example: sample.csv. 





When using Remote Server as our File Information type, we must be sure to put our 
path as relative to the start directory of the FTP connection, once connected. We must 
always include our directory name in the public HTML folder. 


Data Format 


Data Format consists of the following components, shown below: 














Type: CSV / Tab separated xi 
Value Delimiter: À (\t for tab) 
Enclose Values In: ‘a Waming! Empty value can cause problems with CSV format. 
Original Magento attribute | Yes ad 
names in first row: 
Export: Only mapped fields v| 
Type 


Options: MS Excel XML and CSV/Tab Separated. This allows us to choose the file 
type that is going in or out of the profile. 


Original Magento attribute names in first row 
Options: Yes and No. 
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This allows us to define whether or not Magento should check the field names 
against those that are in the Magento attribute database, when importing. It defines 
whether we use only field mapping or use it in combination with standard attribute 
names from the Magneto database. If set to Yes, it will match against Magneto 
attribute names, before looking to the field mapping for answers (about which field 
to map the value against). 


Export 
Options: All fields and Only mapped fields. This is an export only field. 


This decides whether our Export profile will export all fields from the Magento 
attribute database or it will export only the mapping fields that we outline under 
the Field Mapping section. 


Field Mapping 





In Database: | store zj <-> In File: | store 
mo Remove™” 
In Database: | sku +| <--> In File: sku 
“oy Remove” 
In Database: | qty +| <--> In File: | qty 
“To Remove 
In Database: is in_stock +| <--> In File: |is_in_stock 
"ea Remove” 
© Add Field Mapping 











Field mapping allows us to control the fields that are imported/exported. It is 
required before anything is exported, when the Export setting under Data Format 
is set to Only mapped fields. It is required for fields that don't match their existing 
names, on importing. 


It also allows us to change the labels that fields are exported or imported as. For 
example, we can export qt y as quantity because it's more readable in Excel, or we 
could change it to output as product _quantity because this file is to be used to 
import data directly into the database. 
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Export Filters 


This section is extremely valuable when filtering down large datasets for more 
efficient export profiles. It allows us to put in filters to be applied to our dataset, so 
that we create profiles that are specific to certain needs. Below, we see the Export 
Filters screen, when exporting products: 





Name: (Starting with) 
SKU: (Starting with) 
Type: Any Type >j 

Attribute Set Name: Any Attribute Set bd! 

Price: to 

Stock Quantity: to 

Visibility: Any Visibility bad 

Status: Any Status zj 











The Export Filters screen only appears when we select Export in 
>> the Direction field. 


For example: 


e With products, exporting a stock quantity between 0 and 20 would allow 
us to export those products that are low in stock. 


e With products, selecting a certain product type from the Type field would 
allow us to distribute product type management to a relevant department. 


e With customers, selecting our wholesale group would allow us to only 
export our wholesale customers. 


e With customers, we can filter by country to get customers from 
certain countries. 


Upload Files 


The Upload Files tab only appears on import, but allows us to upload files onto 

the server to be processed. Once we've selected our file, we click Save and Continue 
Editing; this will upload the file onto the server. Once it's uploaded, we select 

Run Profile. 
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Import/Export Profile Import Product Stocks 
Profile Wizard Back | EE DS ee eS 
Upload File 
Upload File 


Run Profile 
g Your server PHP settings allow you to upload files not more than 50M at a time, Please modify post_max_size (currently is 50M) and 


Profile Actions XML 
upload_max_filesize (currently is 50M) values in php.ini if you want to upload larger files. 


Profile History 


File 1 Browse.. 
File 2 (Browse... ) 
File 3 (Browse. 











Upload Files appears only in Import profiles and does not relate to 
Rs Export profiles. 


Run Profile 


This is the section from which we can run our profile. We click on Run Profile 

in Popup to initiate the profile, ensuring beforehand that any changes performed 
have been saved. Once we have done this, we will be presented with a series of 
messages until the profile is complete. This will finish with a log of the actions that 
the script has gone through and some debug messages that keep us posted about 
the happenings. 





Import/Export Profile Export Product Stocks ; - 
Profile Wizard Beck | 
Run Profile 
Profile Actions XML g Please make sure that your changes were saved before running the profile. 

Profile History 


© Run Profile In Popup 











If we import, then we will need to upload our files through the Upload File tab and 
select the file from a dropdown before clicking Run Profile in Popup. 
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The profile will not run unless our changes are saved. Hence, we'll need 
as to save changes prior to uploading a file through the profile. 





© Starting profile execution, please wait... 

= Warning: Please don't close window during importing/exporting data 
© Starting Mage_Catalog Model Convert_Adapter_Product :: load 
© Loaded 120 records 

© Starting Mage_Catalog_Model_Convert_Parser_Product :: unparse 
© Starting Mage_Dataflow_Mode!_Convert_Mapper_Column :: map 
@ Starting Mage_Dataflow_Mode!_Convert_Parser_Csv :: unparse 

© Starting Mage_Dataflow_ Model_Convert_Adapter_lo :: save 

© Saved successtully: "export_product_stocks.csv" [3959 byte(s)] 


Finished profile execution. 











Profile Action XML 


From here, we can get the Profile Action XML to be placed into the Advanced 
Profiles section within the Import/Export menu. This section is advancing our 
profile beyond what the default profile builder will allow us to do. 





Import/Export Profile 
Profile Wizard 

Run Profile 

Profile Actions XML 
Profile History 





Export Product Stocks 


oa | rese [0 Sere ara ceninue Eatin 


Actions XML 


<action type="catalog/convert_adapter_product" method="load"> 
<var name="store"><![(CDATA[O]]></var> 
</action> 


<action type="catalog/convert_parser_product” method="unparse"> 
<var name="store"><!(CDATA[0)]></var> 
</action> 


<action type="datafiow/convert_mapper_column" method="map"> 
<var name="map"> 
<map name="store"><![CDATA|store]]></map> 
<map name="sku"><![CDATA|sku]]></map> 
<map name="qty"><![CDATA[aty]]></map> 
<map name="is_in_stock"><!(CDATAis_in_stock]]></map> 
</var> 
<var name="_only_specified">true</var> 
<laction> 


<action type="datafiow/convert_parser_csv" method="unparse"> 
<var name="delimiter"><![CDATAJ,]]></var> 
<var name="enciose"><![CDATA["]]></var> 
<var name="fieldnames">true</var> 

<laction> 


<action type="dataflow/convert_adapter_io" method="save"> 
<var name="type">file</var> 
<var name="path">var/export</var> 
<var name="filename”><I[CDATAlexoort product stocks.csvil></var> 


EAG s. 
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Profile History 


This tab has a history of when the current profile was created, updated, and executed. 
It also provides us with the details of the person who performed these actions. 





Import/Export Profile Export Product Stocks 
Profile Wizard ack | Le o 
Run Profile 
Profile Actions XML Page 1 of 1 pages | View |20 ~| perpage | Total 3 records found Reset Fitter’ | |" Search | 


Profile History Profile Action Performed At + Firstname Lastname 
z| From: 


To: J] 


Update 18 Jan 2009 15:26:58 Jamie Huskisson 
Run 18 Jan 2009 15:13:45 Jamie Huskisson 


Run 18 Jan 2009 14:14:22 Jamie Huskisson 











Sample implementation: Import/Export 
of metadata 


A sample usage of importing/exporting data in Magento is to use it to control the 
product metadata stored for all of our products. Sometimes SEO (Search Engine 
Optimization) companies want to tweak metadata en masse. When using Magento's 
import/export functionality, this reduces the overhead of appointing someone to 
traverse the data, product-by-product, to edit everything. 


To do this, we create: 


e An export profile to get all of our product metadata out for us to edit 
and manage 


e Animport profile to import all of our changes back into the system 


Exporting our metadata 


We begin by creating a new profile. For that, we click on the Add New Profile button 
in the top-right of the initial Profiles screen. 


For setting up our metadata export profile, we have the following settings: 
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Setting up the Profile Information 


This will be a products export profile across all stores and should be named Export 
META Data. 








Field Value 

Name Export META Data 
Entity Type Products 

Direction Export 

Store Default (Admin) Values 


Adding the File Information 


Our file should be stored in / var/ export and be named as meta_data_export. xml 
on our local server, once the profile has been executed. 








Field Value 

Data transfer Local/ Remote server 
Type Local server 

File Name meta_data_export. xml 
Path var/export 





Selecting the Data Format 


We try an MS Excel XML formatted file with a spreadsheet named Meta Data. This 
format has its advantages over CSV, as its less prone to formatting issues causing 
rows to not import. There is more of an internal file structure separating data, which 
leads to better results when using it. 


We set it only to mapped fields which we outline and ensure that Magento attribute 
names will not be used. 








Field Value 
Type MS Excel XML 
Spreadsheet Name Meta Data 


Original Magento Attribute Names No 


in the first row 
Export Only mapped fields 
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Mapping our fields 


We stick to only meta information fields and the store/sku values, so that we have 
product relation covered when we import back into Magento. To make things a little 
more interesting, we customize the field names. 








Original field Mapped to 

store store code 

Sku product sku 
meta_title meta_data_ title 
meta_keyword meta_data_keyword 
meta_description meta_data_ description 





Choosing the Export Filters 


Here we limit the number of export filters, so that only enabled products are 
exported, to cut down on unnecessary changes to products not on the site. 


Field Value 
Status Enabl ed 





Once saved, we go back to the Run Profile section to export our file. After this is 
done, we go into the/ var/ export directory within the Magento setup directory to 
find the exported file of product metadata. 


When we open this file in MS Excel, it appears nicely (as any normal spreadsheet 
would), with our spreadsheet name as outlined previously. We make a few random 
edits, and take note of the products that we have edited for future use, when we 
wish to ensure that the import has worked. 


Importing our metadata 


Now that we have our export profile and we've edited all of our data, we need to 
be able to import our changes back and have Magento process them. To do this, we 
need to set up a profile to import and process this data correctly. 


Now, we set up another profile with the following settings for our import profile: 
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Setting up the Profile Information 


This will be a products import profile across all stores and be named Import 
META Data. 








Field Value 

Name Import META Data 
Entity Type Products 

Direction | mport 

Store Default (Admin) Values 
Number of records 1 


Decimal Separator 





Adding the File Information 


We make the profile interactive, so that we can upload our own file to be executed 
and processed. 





Field Value 
Data transfer Interactive 








Selecting the Data Format 


We use MS Excel XML with a spreadsheet named Meta Data, limiting it to only 
mapped fields (outlined by us). We ensure that Magento attribute names will be 
used in the first row. 








Field Value 

Type MS Excel XML 
Spreadsheet Name Meta Data 
Original Magento Attributes No 

Names 


in the first row 
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Mapping our fields 


We map the fields similar to how we did before. 








Original field Mapped to 

store store code 

Sku product sku 
meta_title meta_data_ title 

meta keyword meta _data_keyword 
meta_description meta_data_description 





Once we set this up, we click the Save and Continue Editing button and go to 
Upload File on the left sub-navigation menu and upload our changed file via the 
Upload File tab. Then we click on Save and Continue Editing and return to the Run 
Profile tab. Then we select the file that we just uploaded from the drop-down list and 
run our import profile through. The following screenshot will be displayed: 





= Starting profile execution, please wait... 

— Warning: Please don't close window during importing/exporting data 
© Starting Mage_Dataflow_Model_Convert_Parser_Xml_Excel :; parse 
© Found 119 rows 

@ Starting catalog/convert_adapter_product :: parse 


© Processed 100% 119/119 records 





© Imported 119 records 








The profile has been imported successfully and the test run updated all the profiles 
without fail. We check our products via thes ku values that we changed under 
Manage->Manage Products. We find that the META data information has now 
been updated. 
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Common issues with importing/exporting 


The following issues are encountered while importing/ exporting. 


Bad CSV file formatting 


Often the cause of a bad import and missing rows from the import, is that of bad 

file formatting. This case is more likely to occur in the CSV file format than MS 
Excel. This happens because the CSV file type is much more prone to data breakages 
through bad formatting. 


Short descriptions 


Although we can make sure a short description goes on for as long as we like within 
Magento, via Profiles we should ensure that it isn't more than 255 characters. 


Import/export paths 


We need to verify that they are writeable. It sounds like an obvious mistake, but 
many developers don't look at the basics before they look into why everything is 
going wrong. 


Images location 


We need to ensure that if we import images with your products, they are placed in 
| medi a/i mpor t . Otherwise, they will throw errors and will not be imported. If the 
value of our image column is/sub-directory/image_name. j pg, then the URL to 
where the image should be placed within Magento installation is: medi a/ i mport / 
Sub-directory/image_ name. jpg. 


Importing multiple images 
In our CSV/MS Excel XML file, adding either multiple image or small images, or 
thumb columns to add multiple images into the product, causes a problem. 
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Summary 


In this chapter, we have learned: 


What types of data we can export from Magento from a default installation 
What types of data we can import into Magento from a default installation 
The file types that we can use for these actions 

How to set up our own data profile in order to import/export data ourselves 
How to manage META data en masse using these profiles 


How to solve some of the common issues in the profile functionality 


Further to this, we should try and experiment with Magento's import/export data 
functionality. We should be able to comfortably manage the data profiles that are 
included in the default Magento installation and should be able to create our own 
basic profiles. 
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